@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/compatibility.js

@@ -0,0 +1,66 @@
+import { createRequire } from 'node:module';
+export const COMPATIBILITY_SCHEMA = 'dsh-data-analysis-compatibility/v2';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requiredString(value, location) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${location} must be a non-empty string`);
+    }
+    return value;
+}
+function requiredLiteral(value, expected, location) {
+    if (value !== expected)
+        throw new TypeError(`${location} must be ${expected}`);
+    return expected;
+}
+function stringRecord(value, location) {
+    if (!isRecord(value))
+        throw new TypeError(`${location} must be an object`);
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, requiredString(item, `${location}.${key}`)])));
+}
+function parsePackageManifest(value) {
+    if (!isRecord(value))
+        throw new TypeError('package.json must contain an object');
+    const compatibility = value.dshDataAnalysisCompatibility;
+    if (!isRecord(compatibility)) {
+        throw new TypeError('package.json.dshDataAnalysisCompatibility must be an object');
+    }
+    const dsh = compatibility.dsh;
+    const marivo = compatibility.marivo;
+    const contracts = compatibility.contracts;
+    if (!isRecord(dsh) || !isRecord(marivo) || !isRecord(contracts)) {
+        throw new TypeError('package compatibility dsh, marivo, and contracts must be objects');
+    }
+    return Object.freeze({
+        version: requiredString(value.version, 'package.json.version'),
+        peerDependencies: stringRecord(value.peerDependencies, 'package.json.peerDependencies'),
+        dshDataAnalysisCompatibility: Object.freeze({
+            schema: requiredLiteral(compatibility.schema, COMPATIBILITY_SCHEMA, 'package compatibility schema'),
+            dsh: Object.freeze({
+                distribution: requiredLiteral(dsh.distribution, '@deepseek-ai/dsh', 'package compatibility dsh.distribution'),
+                peerRange: requiredString(dsh.peerRange, 'package compatibility dsh.peerRange'),
+            }),
+            marivo: Object.freeze({
+                version: requiredString(marivo.version, 'package compatibility marivo.version'),
+                packageSpec: requiredString(marivo.packageSpec, 'package compatibility marivo.packageSpec'),
+            }),
+            contracts: Object.freeze({
+                runtimeInstallation: requiredLiteral(contracts.runtimeInstallation, 'dsh-data-analysis-runtime/v2', 'package compatibility contracts.runtimeInstallation'),
+                subprocessPolicy: requiredLiteral(contracts.subprocessPolicy, 'direct-argv-inherited-env-snapshot-overlay-v2', 'package compatibility contracts.subprocessPolicy'),
+            }),
+        }),
+    });
+}
+const packageManifest = parsePackageManifest(createRequire(import.meta.url)('../package.json'));
+/** The package semver and the compatibility contract shipped in this exact installation. */
+export const PLUGIN_VERSION = packageManifest.version;
+export const DSH_DATA_ANALYSIS_COMPATIBILITY = packageManifest.dshDataAnalysisCompatibility;
+/** Every DSH peer is required and must use this one verified release. */
+export const DSH_PEER_RANGE = DSH_DATA_ANALYSIS_COMPATIBILITY.dsh.peerRange;
+export const DSH_DISTRIBUTION = DSH_DATA_ANALYSIS_COMPATIBILITY.dsh.distribution;
+export const DSH_PEER_DEPENDENCIES = Object.freeze(Object.fromEntries(Object.entries(packageManifest.peerDependencies).filter(([name]) => name.startsWith('@deepseek-ai/dsh-'))));
+export const MARIVO_VERSION = DSH_DATA_ANALYSIS_COMPATIBILITY.marivo.version;
+export const MARIVO_PACKAGE_SPEC = DSH_DATA_ANALYSIS_COMPATIBILITY.marivo.packageSpec;
+export const RUNTIME_INSTALLATION_VERSION = DSH_DATA_ANALYSIS_COMPATIBILITY.contracts.runtimeInstallation;
+export const SUBPROCESS_POLICY_VERSION = DSH_DATA_ANALYSIS_COMPATIBILITY.contracts.subprocessPolicy;

package/lib/datasource/access.js

@@ -0,0 +1,60 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveMarivoDatasourceBridge, } from "./bridge.js";
+import { inspectMarivoDatasourceCredentials } from "./credentials.js";
+export const MARIVO_DATASOURCE_ACCESS_TOOL_NAME = 'marivo_datasource_access';
+function datasourceName(value) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 256) {
+        throw new TypeError('marivo_datasource_access name must be a non-empty string of at most 256 characters');
+    }
+    return value;
+}
+function renderValue(value) {
+    if (value.status === 'needs-credentials')
+        return JSON.stringify(value);
+    return [
+        `Marivo datasource ${value.name} foreground Shell access is ready for up to ${value.shell_lease.max_uses} executions within ${value.shell_lease.expires_in_ms} ms.`,
+        'Copy every line of the matching prelude verbatim before each foreground analysis command.',
+        'The first line beginning with "# dsh-marivo-credential-lease:" is a required control marker; do not remove or move it.',
+        'Use run_in_background=false (or omit it). If a datasource credential environment variable is missing, reacquire access; never read DSH credential files or ~/.marivo/secrets.toml.',
+        `bash prelude:\n${value.shell_lease.bash_prelude}`,
+        `pwsh prelude:\n${value.shell_lease.pwsh_prelude}`,
+    ].join('\n');
+}
+/** Build the scoped datasource access Tool without performing a connection test. */
+export function createMarivoDatasourceAccessTool(bridgeSource, credentials, options) {
+    return defineTool({
+        name: MARIVO_DATASOURCE_ACCESS_TOOL_NAME,
+        description: 'Acquire bounded foreground Shell access for one configured Marivo datasource without testing its connection.',
+        parameters: {
+            name: {
+                type: 'string',
+                required: true,
+                description: 'Configured Marivo datasource name.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [
+                { type: 'text', text: renderValue(value) },
+            ],
+        },
+        async execute(args, exec) {
+            const name = datasourceName(args.name);
+            const bridge = await resolveMarivoDatasourceBridge(bridgeSource);
+            options.revokeShellLease(bridge, name);
+            const described = await bridge.describe(name, exec.signal);
+            const missing = await inspectMarivoDatasourceCredentials(described.refs, credentials, exec.signal);
+            if (missing.length > 0) {
+                return { status: 'needs-credentials', name: described.name, refs: missing };
+            }
+            return {
+                status: 'ok',
+                name: described.name,
+                shell_lease: options.issueShellLease(bridge, described.name, described.refs),
+            };
+        },
+    });
+}
+export function registerMarivoDatasourceAccessTool(ctx, bridgeSource, credentials, options) {
+    return ctx.tools.register(createMarivoDatasourceAccessTool(bridgeSource, credentials, options));
+}

package/lib/datasource/bridge-programs.js

@@ -0,0 +1,80 @@
+export const MARIVO_DATASOURCE_DESCRIBE_PROGRAM = String.raw `
+import json
+import os
+import sys
+import marivo
+import marivo.datasource as md
+
+description = md.describe(sys.argv[1])
+print(json.dumps({
+    "name": description.name,
+    "refs": list(description.env_refs.values()),
+}, sort_keys=True))
+`.trim();
+export const MARIVO_DATASOURCE_INVENTORY_PROGRAM = String.raw `
+import json
+import os
+import sys
+import marivo
+import marivo.datasource as md
+
+print(json.dumps({
+    "datasources": [{
+        "name": description.name,
+        "refs": list(description.env_refs.values()),
+    } for description in (md.describe(item.name) for item in md.list())],
+}, sort_keys=True))
+`.trim();
+export const MARIVO_DATASOURCE_TEST_PROGRAM = String.raw `
+import contextlib
+import io
+import json
+import os
+import sys
+import marivo
+import marivo.datasource as md
+
+captured_stdout = io.StringIO()
+captured_stderr = io.StringIO()
+try:
+    with contextlib.redirect_stdout(captured_stdout), contextlib.redirect_stderr(captured_stderr):
+        description = md.describe(sys.argv[1])
+        secret_values = [
+            value
+            for ref in description.env_refs.values()
+            if (value := os.environ.get(ref))
+        ]
+        result = md.test(sys.argv[1])
+except Exception as exc:
+    print(json.dumps({"kind": "datasource-test-failed", "exception_type": type(exc).__name__}), file=sys.stderr)
+    raise SystemExit(70)
+
+def redact(value):
+    if isinstance(value, str):
+        for secret in secret_values:
+            value = value.replace(secret, "[REDACTED]")
+        return value
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    if isinstance(value, tuple):
+        return [redact(item) for item in value]
+    if isinstance(value, dict):
+        return {key: redact(item) for key, item in value.items()}
+    return value
+
+failure = None if result.failure is None else {
+    "code": result.failure.code,
+    "exception_type": result.failure.exception_type,
+    "backend_code": result.failure.backend_code,
+    "backend_name": result.failure.backend_name,
+    "message": result.failure.message,
+}
+repair = None if result.repair is None else result.repair.model_dump(mode="json")
+print(json.dumps(redact({
+    "name": result.name,
+    "ok": result.ok,
+    "latency_ms": result.latency_ms,
+    "failure": failure,
+    "repair": repair,
+}), sort_keys=True))
+`.trim();

package/lib/datasource/bridge.js

@@ -0,0 +1,204 @@
+import { isCredentialRefName } from '@deepseek-ai/dsh-credentials';
+import { MarivoEnvironmentError } from "../environment/errors.js";
+import { resolveMarivoBridgeSource } from "../environment/source.js";
+import { MARIVO_DATASOURCE_DESCRIBE_PROGRAM, MARIVO_DATASOURCE_INVENTORY_PROGRAM, MARIVO_DATASOURCE_TEST_PROGRAM, } from "./bridge-programs.js";
+const DATASOURCE_LIMITS = Object.freeze({
+    timeoutMs: 30_000,
+    stdoutMaxBytes: 262_144,
+    stderrMaxBytes: 65_536,
+});
+function exactKeys(value, keys, phase) {
+    const expected = new Set(keys);
+    if (Object.keys(value).some((key) => !expected.has(key)) || keys.some((key) => !(key in value))) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource ${phase} returned an unexpected payload shape`, { phase });
+    }
+}
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function string(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function nullableString(value) {
+    return value === null || typeof value === 'string';
+}
+function parseJsonObject(stdout, phase) {
+    try {
+        const parsed = JSON.parse(stdout.toString('utf8'));
+        if (object(parsed) === undefined) {
+            throw new TypeError('payload must be an object');
+        }
+        return parsed;
+    }
+    catch (cause) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource ${phase} returned an invalid payload`, { phase, stdoutBytes: stdout.byteLength }, { cause });
+    }
+}
+function parseDescription(value, phase) {
+    const source = object(value);
+    if (source === undefined) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource ${phase} returned invalid fields`, { phase });
+    }
+    exactKeys(source, ['name', 'refs'], phase);
+    const name = string(source.name);
+    if (name === undefined || !Array.isArray(source.refs)) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource ${phase} returned invalid fields`, { phase });
+    }
+    const refs = [];
+    const seen = new Set();
+    for (const ref of source.refs) {
+        if (typeof ref !== 'string' || !isCredentialRefName(ref)) {
+            throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource ${phase} returned an invalid credential reference`, { phase });
+        }
+        if (!seen.has(ref)) {
+            seen.add(ref);
+            refs.push(ref);
+        }
+    }
+    return { name, refs };
+}
+function parseInventory(stdout) {
+    const value = parseJsonObject(stdout, 'inventory');
+    exactKeys(value, ['datasources'], 'inventory');
+    if (!Array.isArray(value.datasources)) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo datasource inventory returned invalid fields', { phase: 'datasource-inventory' });
+    }
+    return value.datasources.map((item) => parseDescription(item, 'inventory'));
+}
+function parseFailure(value) {
+    const source = object(value);
+    if (source === undefined)
+        throw new TypeError('failure must be an object');
+    exactKeys(source, ['code', 'exception_type', 'backend_code', 'backend_name', 'message'], 'test');
+    if (string(source.code) === undefined ||
+        string(source.exception_type) === undefined ||
+        !nullableString(source.backend_code) ||
+        !nullableString(source.backend_name) ||
+        typeof source.message !== 'string') {
+        throw new TypeError('failure fields are invalid');
+    }
+    return source;
+}
+function parseRepair(value) {
+    const source = object(value);
+    if (source === undefined)
+        throw new TypeError('repair must be an object');
+    exactKeys(source, ['kind', 'help_target', 'action', 'snippet', 'candidates', 'preserves_evidence'], 'test');
+    if (string(source.kind) === undefined ||
+        string(source.help_target) === undefined ||
+        typeof source.action !== 'string' ||
+        !nullableString(source.snippet) ||
+        !Array.isArray(source.candidates) ||
+        source.candidates.some((item) => typeof item !== 'string') ||
+        (source.preserves_evidence !== null && typeof source.preserves_evidence !== 'boolean')) {
+        throw new TypeError('repair fields are invalid');
+    }
+    return source;
+}
+function redactUnknown(value, secrets) {
+    if (typeof value === 'string') {
+        let result = value;
+        for (const secret of secrets)
+            if (secret !== '')
+                result = result.split(secret).join('[REDACTED]');
+        return result;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => redactUnknown(item, secrets));
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactUnknown(item, secrets)]));
+}
+function parseTest(stdout, secrets) {
+    const value = redactUnknown(parseJsonObject(stdout, 'test'), secrets);
+    exactKeys(value, ['name', 'ok', 'latency_ms', 'failure', 'repair'], 'test');
+    if (string(value.name) === undefined ||
+        typeof value.ok !== 'boolean' ||
+        (value.latency_ms !== null &&
+            (typeof value.latency_ms !== 'number' ||
+                !Number.isFinite(value.latency_ms) ||
+                value.latency_ms < 0))) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', `Marivo datasource test returned invalid fields (name=${typeof value.name}, ok=${typeof value.ok}, latency=${value.latency_ms === null ? 'null' : typeof value.latency_ms})`, { phase: 'test' });
+    }
+    if (value.ok) {
+        if (value.failure !== null || value.repair !== null) {
+            throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo datasource test success included failure or repair fields', { phase: 'test' });
+        }
+        return {
+            name: value.name,
+            ok: true,
+            latency_ms: value.latency_ms,
+            failure: null,
+            repair: null,
+        };
+    }
+    if (value.failure === null || value.repair === null) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo datasource test failure omitted structured failure or repair', { phase: 'test' });
+    }
+    try {
+        return {
+            name: value.name,
+            ok: false,
+            latency_ms: value.latency_ms,
+            failure: parseFailure(value.failure),
+            repair: parseRepair(value.repair),
+        };
+    }
+    catch (cause) {
+        if (cause instanceof MarivoEnvironmentError)
+            throw cause;
+        throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo datasource test returned invalid failure or repair fields', { phase: 'test' }, { cause });
+    }
+}
+/** Identity-checked adapter for Marivo datasource metadata and connection tests. */
+export class MarivoDatasourceBridge {
+    binding;
+    #runner;
+    constructor(runner) {
+        this.#runner = runner;
+        this.binding = runner.binding;
+    }
+    async describe(name, signal) {
+        const result = await this.#runner.runChecked({
+            program: MARIVO_DATASOURCE_DESCRIBE_PROGRAM,
+            args: [name],
+            limits: DATASOURCE_LIMITS,
+            signal,
+        });
+        this.#assertSuccess(result, 'describe');
+        return parseDescription(parseJsonObject(result.stdout, 'describe'), 'describe');
+    }
+    async inventory(signal) {
+        const result = await this.#runner.runChecked({
+            program: MARIVO_DATASOURCE_INVENTORY_PROGRAM,
+            limits: DATASOURCE_LIMITS,
+            signal,
+        });
+        this.#assertSuccess(result, 'inventory');
+        return parseInventory(result.stdout);
+    }
+    async test(name, environmentOverlay, signal) {
+        const result = await this.#runner.runChecked({
+            program: MARIVO_DATASOURCE_TEST_PROGRAM,
+            args: [name],
+            environmentOverlay,
+            limits: DATASOURCE_LIMITS,
+            signal,
+        });
+        this.#assertSuccess(result, 'test');
+        return parseTest(result.stdout, Object.values(environmentOverlay).filter((value) => Boolean(value)));
+    }
+    #assertSuccess(result, phase) {
+        if (result.exitCode === 0)
+            return;
+        throw new MarivoEnvironmentError('subprocess-failed', `Marivo datasource ${phase} failed with exit code ${String(result.exitCode)}`, { phase, exitCode: result.exitCode, stderr: result.stderr.toString('utf8').slice(0, 2_000) });
+    }
+}
+export function resolveMarivoDatasourceBridge(source) {
+    return resolveMarivoBridgeSource(source);
+}
+export function resolveMarivoDatasourceInventoryBridge(source) {
+    return resolveMarivoBridgeSource(source);
+}

package/lib/datasource/credentials.js

@@ -0,0 +1,24 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { MarivoEnvironmentError } from "../environment/index.js";
+import { assertMarivoCredentialReferences, marivoCredentialStorageRef } from "./shell-env.js";
+/** Resolve mapped credentials once and optionally project values into an operation overlay. */
+export async function inspectMarivoDatasourceCredentials(refs, credentials, signal, accept) {
+    const uniqueRefs = [...new Set(refs)];
+    assertMarivoCredentialReferences(uniqueRefs);
+    const missing = [];
+    for (const ref of uniqueRefs) {
+        signal.throwIfAborted();
+        let resolved;
+        try {
+            resolved = await credentials.resolve(credentialRef(marivoCredentialStorageRef(ref)));
+        }
+        catch {
+            throw new MarivoEnvironmentError('datasource-credential-resolve-failed', 'A mapped Marivo datasource credential could not be resolved', { ref });
+        }
+        if (resolved === undefined)
+            missing.push(ref);
+        else
+            accept?.(ref, resolved.value);
+    }
+    return missing;
+}

package/lib/datasource/index.js

@@ -0,0 +1,4 @@
+export { createMarivoDatasourceAccessTool, MARIVO_DATASOURCE_ACCESS_TOOL_NAME, registerMarivoDatasourceAccessTool, } from "./access.js";
+export { MarivoDatasourceBridge, resolveMarivoDatasourceBridge, resolveMarivoDatasourceInventoryBridge, } from "./bridge.js";
+export { assertMarivoCredentialReferences, DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES, DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS, MARIVO_CREDENTIAL_LEASE_PREFIX, MARIVO_CREDENTIAL_STORAGE_PREFIX, MarivoShellCredentialLeases, marivoCredentialStorageRef, } from "./shell-env.js";
+export { createMarivoDatasourceTestTool, MARIVO_DATASOURCE_TEST_TOOL_NAME, registerMarivoDatasourceTestTool, } from "./test.js";