502 lines
18 KiB
TypeScript
502 lines
18 KiB
TypeScript
import { expect, test } from "vitest";
|
|
import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { parse } from "yaml";
|
|
import { buildInstallationContract, renderWorkspaceDocs } from "../src/workspaces/contracts.js";
|
|
import { type CanonicalWorkspace, parseWorkspaceYaml } from "../src/workspaces/schema.js";
|
|
import { renderRuntimeConfig, type RuntimeBindings } from "../src/workspaces/runtime-renderer.js";
|
|
|
|
const validWorkspace = parseWorkspaceYaml(`workspace:
|
|
schema_version: 2
|
|
id: psd-clinical
|
|
name: Policlinico San Donato
|
|
language: it
|
|
dwh:
|
|
engine: postgres
|
|
database: postgres
|
|
schema: datawarehouse
|
|
supported_transports:
|
|
- postgres_direct
|
|
- rest_api
|
|
semantic_index:
|
|
vector_store:
|
|
engine: pgvector
|
|
database: postgres
|
|
schema: vectors
|
|
collection: clinical_documents
|
|
dimensions: 768
|
|
distance: cosine
|
|
supported_transports:
|
|
- pgvector_direct
|
|
- rest_api
|
|
embedding:
|
|
provider: ollama_compatible
|
|
model: nomic-embed-text-v2-moe
|
|
dimensions: 768
|
|
llm_policy:
|
|
default: zai/glm-5.2
|
|
allowed:
|
|
- zai/glm-5.2
|
|
- openai/gpt-5
|
|
`);
|
|
const workspaceV3 = parseWorkspaceYaml(`workspace:
|
|
schema_version: 3
|
|
id: psd-clinical
|
|
name: Policlinico San Donato
|
|
language: it
|
|
dwh:
|
|
engine: postgres
|
|
database: postgres
|
|
schema: datawarehouse
|
|
supported_transports: [postgres_direct, rest_api]
|
|
semantic_index:
|
|
vector_store:
|
|
engine: qdrant
|
|
collection: psd-clinical
|
|
dimensions: 1024
|
|
distance: cosine
|
|
embedding:
|
|
provider: ollama_internal
|
|
model: qwen3-embedding:0.6b
|
|
dimensions: 1024
|
|
llm_policy:
|
|
allowed: [zai/glm-5.2]
|
|
`);
|
|
|
|
test("generates stable FILE-based secret requirements from an immutable ID", () => {
|
|
const contract = buildInstallationContract(validWorkspace);
|
|
|
|
expect(contract.variables.map((variable) => variable.name))
|
|
.toContain("THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE");
|
|
expect(contract.variables.filter((variable) => variable.secret).every((variable) => (
|
|
variable.name.endsWith("_FILE")
|
|
))).toBe(true);
|
|
expect(renderWorkspaceDocs(validWorkspace).envExample).not.toContain("secret-value");
|
|
});
|
|
|
|
test("derives variable names from fixed role and suffix metadata", () => {
|
|
const contract = buildInstallationContract(validWorkspace);
|
|
const password = contract.variables.find((variable) => (
|
|
variable.role === "DWH" && variable.suffix === "PASSWORD_FILE"
|
|
));
|
|
|
|
expect(password).toMatchObject({
|
|
name: "THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE",
|
|
role: "DWH",
|
|
suffix: "PASSWORD_FILE",
|
|
secret: true,
|
|
});
|
|
});
|
|
|
|
test("renders English UI headings and workspace-language Italian prose", () => {
|
|
const docs = renderWorkspaceDocs(validWorkspace);
|
|
|
|
expect(docs.markdown).toContain("# Installation requirements");
|
|
expect(docs.markdown).toContain("Configurazione dell'installazione");
|
|
expect(docs.markdown).not.toContain("## Vector writer");
|
|
expect(docs.envExample).toContain("THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=");
|
|
});
|
|
|
|
test("schema v3 installation contracts expose only DWH bindings and no semantic variables", () => {
|
|
const contract = buildInstallationContract(workspaceV3);
|
|
const names = contract.variables.map((variable) => variable.name);
|
|
const docs = renderWorkspaceDocs(workspaceV3);
|
|
|
|
expect(contract.variables.every((variable) => variable.role === "DWH")).toBe(true);
|
|
expect(names).toContain("THT_WS_PSD_CLINICAL_DWH_TRANSPORT");
|
|
expect(names.some((name) => /_VECTOR_|_EMBEDDING_/.test(name))).toBe(false);
|
|
expect(docs.envExample).not.toContain("_VECTOR_");
|
|
expect(docs.envExample).not.toContain("_EMBEDDING_");
|
|
expect(docs.markdown).not.toContain("Vector store");
|
|
expect(docs.markdown).not.toContain("Embedding service");
|
|
});
|
|
|
|
test("renders the vector store identity and creates writer credentials only when declared", () => {
|
|
const writerWorkspace = parseWorkspaceYaml(`workspace:
|
|
schema_version: 2
|
|
id: psd-clinical
|
|
name: Policlinico San Donato
|
|
language: it
|
|
dwh:
|
|
engine: postgres
|
|
database: warehouse
|
|
schema: datawarehouse
|
|
supported_transports: [postgres_direct, rest_api]
|
|
semantic_index:
|
|
vector_store:
|
|
engine: pgvector
|
|
database: vector_database
|
|
schema: vectors
|
|
collection: clinical_documents
|
|
dimensions: 768
|
|
distance: cosine
|
|
supported_transports: [pgvector_direct, rest_api]
|
|
vector_writer: {}
|
|
embedding:
|
|
provider: ollama_compatible
|
|
model: nomic-embed-text-v2-moe
|
|
dimensions: 768
|
|
diagnostics:
|
|
dwh_rest:
|
|
method: POST
|
|
path: /rpc/ping
|
|
auth: bearer
|
|
response:
|
|
database: database
|
|
schema: schema
|
|
vector_rest:
|
|
metadata:
|
|
method: GET
|
|
path: /metadata
|
|
auth: bearer
|
|
response:
|
|
collection: collection
|
|
dimensions: dimensions
|
|
distance: distance
|
|
embedding:
|
|
method: GET
|
|
path: /models
|
|
auth: none
|
|
response:
|
|
model: model
|
|
dimensions: dimensions
|
|
llm_policy:
|
|
allowed: [zai/glm-5.2]
|
|
`);
|
|
const bindings: RuntimeBindings = {
|
|
dwh: {
|
|
transport: "postgres_direct",
|
|
missing: [],
|
|
values: {
|
|
THT_WS_PSD_CLINICAL_DWH_HOST: "dwh.internal",
|
|
THT_WS_PSD_CLINICAL_DWH_PORT: "5432",
|
|
THT_WS_PSD_CLINICAL_DWH_USER: "reader",
|
|
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE: "/run/secrets/dwh",
|
|
},
|
|
},
|
|
vector: {
|
|
transport: "pgvector_direct",
|
|
missing: [],
|
|
values: {
|
|
THT_WS_PSD_CLINICAL_VECTOR_HOST: "vector.internal",
|
|
THT_WS_PSD_CLINICAL_VECTOR_PORT: "5432",
|
|
THT_WS_PSD_CLINICAL_VECTOR_USER: "vector-reader",
|
|
THT_WS_PSD_CLINICAL_VECTOR_PASSWORD_FILE: "/run/secrets/vector-reader",
|
|
},
|
|
},
|
|
vectorWriter: { transport: "rest_api", missing: [], values: {} },
|
|
embedding: {
|
|
transport: "rest_api",
|
|
missing: [],
|
|
values: { THT_WS_PSD_CLINICAL_EMBEDDING_BASE_URL: "https://embedding.internal" },
|
|
},
|
|
evidence: { missing: [], values: {} },
|
|
};
|
|
|
|
const writerVariables = buildInstallationContract(writerWorkspace).variables
|
|
.filter((variable) => variable.role === "VECTOR_WRITER");
|
|
|
|
expect(writerVariables).toEqual([expect.objectContaining({
|
|
name: "THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE",
|
|
role: "VECTOR_WRITER",
|
|
secret: true,
|
|
})]);
|
|
expect(buildInstallationContract(validWorkspace).variables.some((variable) => (
|
|
variable.role === "VECTOR_WRITER"
|
|
))).toBe(false);
|
|
expect(parse(renderRuntimeConfig(writerWorkspace, bindings, {
|
|
sessions: "/data/sessions",
|
|
artifacts: "/data/artifacts",
|
|
indexes: "/data/indexes",
|
|
})).vector_db).toMatchObject({ database: "vector_database", schema: "vectors" });
|
|
});
|
|
|
|
test("renders legacy writer secret-file bindings without reintroducing them to the active protocol", () => {
|
|
const writerVariable = "THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE";
|
|
const generated = renderWorkspaceDocs(parseWorkspaceYaml(`workspace:
|
|
schema_version: 2
|
|
id: psd-clinical
|
|
name: Policlinico San Donato
|
|
language: it
|
|
dwh:
|
|
engine: postgres
|
|
database: warehouse
|
|
schema: datawarehouse
|
|
supported_transports: [postgres_direct]
|
|
semantic_index:
|
|
vector_store:
|
|
engine: pgvector
|
|
database: vector_database
|
|
schema: vectors
|
|
collection: clinical_documents
|
|
dimensions: 768
|
|
distance: cosine
|
|
supported_transports: [rest_api]
|
|
vector_writer: {}
|
|
embedding:
|
|
provider: ollama_compatible
|
|
model: nomic-embed-text-v2-moe
|
|
dimensions: 768
|
|
llm_policy:
|
|
allowed: [zai/glm-5.2]
|
|
`));
|
|
const protocolPath = fileURLToPath(new URL("../../docs/workspace-diagnostic-protocol.md", import.meta.url));
|
|
|
|
expect(generated.markdown).toContain(`\`${writerVariable}\``);
|
|
expect(generated.envExample).toContain(`${writerVariable}=`);
|
|
expect(existsSync(protocolPath)).toBe(true);
|
|
if (existsSync(protocolPath)) {
|
|
expect(readFileSync(protocolPath, "utf8")).not.toContain(writerVariable);
|
|
expect(readFileSync(protocolPath, "utf8")).toContain("There are no supported `THT_WS_<NAMESPACE>_VECTOR_*`");
|
|
}
|
|
});
|
|
|
|
function withTransports(
|
|
dwhTransport: CanonicalWorkspace["dwh"]["supported_transports"][number],
|
|
vectorTransport: CanonicalWorkspace["semantic_index"]["vector_store"]["supported_transports"][number],
|
|
): CanonicalWorkspace {
|
|
return {
|
|
...validWorkspace,
|
|
dwh: { ...validWorkspace.dwh, supported_transports: [dwhTransport] },
|
|
semantic_index: {
|
|
...validWorkspace.semantic_index,
|
|
vector_store: {
|
|
...validWorkspace.semantic_index.vector_store,
|
|
supported_transports: [vectorTransport],
|
|
},
|
|
},
|
|
};
|
|
}
|
|
|
|
test("emits only direct connector bindings for direct transports", () => {
|
|
const variables = buildInstallationContract(withTransports("postgres_direct", "pgvector_direct")).variables;
|
|
|
|
for (const role of ["DWH", "VECTOR"] as const) {
|
|
const names = variables.filter((variable) => variable.role === role).map((variable) => variable.name);
|
|
expect(names).toContain(`THT_WS_PSD_CLINICAL_${role}_HOST`);
|
|
expect(names).toContain(`THT_WS_PSD_CLINICAL_${role}_PASSWORD_FILE`);
|
|
expect(names).not.toContain(`THT_WS_PSD_CLINICAL_${role}_BASE_URL`);
|
|
expect(names).not.toContain(`THT_WS_PSD_CLINICAL_${role}_API_KEY_FILE`);
|
|
expect(names.some((name) => name.includes("_SSH_"))).toBe(false);
|
|
}
|
|
});
|
|
|
|
test("emits only REST connector bindings for REST transports", () => {
|
|
const variables = buildInstallationContract(withTransports("rest_api", "rest_api")).variables;
|
|
|
|
for (const role of ["DWH", "VECTOR"] as const) {
|
|
const names = variables.filter((variable) => variable.role === role).map((variable) => variable.name);
|
|
expect(names).toContain(`THT_WS_PSD_CLINICAL_${role}_BASE_URL`);
|
|
expect(names).toContain(`THT_WS_PSD_CLINICAL_${role}_API_KEY_FILE`);
|
|
expect(names).not.toContain(`THT_WS_PSD_CLINICAL_${role}_HOST`);
|
|
expect(names).not.toContain(`THT_WS_PSD_CLINICAL_${role}_PASSWORD_FILE`);
|
|
expect(names.some((name) => name.includes("_SSH_"))).toBe(false);
|
|
}
|
|
});
|
|
|
|
test("emits SSH bindings only for SSH-tunnel transports", () => {
|
|
const variables = buildInstallationContract(withTransports("ssh_tunnel", "ssh_tunnel")).variables;
|
|
|
|
for (const role of ["DWH", "VECTOR"] as const) {
|
|
const roleVariables = variables.filter((variable) => variable.role === role);
|
|
expect(roleVariables.map((variable) => variable.name))
|
|
.toContain(`THT_WS_PSD_CLINICAL_${role}_SSH_PRIVATE_KEY_FILE`);
|
|
expect(roleVariables.find((variable) => variable.suffix === "SSH_HOST")?.transports)
|
|
.toEqual(["ssh_tunnel"]);
|
|
expect(roleVariables.map((variable) => variable.name))
|
|
.not.toContain(`THT_WS_PSD_CLINICAL_${role}_BASE_URL`);
|
|
}
|
|
});
|
|
|
|
test("validates public contract and documentation inputs at runtime", () => {
|
|
const unsafeWorkspace = {
|
|
...validWorkspace,
|
|
workspace: { ...validWorkspace.workspace, id: "psd\nclinical" },
|
|
} as CanonicalWorkspace;
|
|
|
|
expect(() => buildInstallationContract(unsafeWorkspace)).toThrow(/id/i);
|
|
expect(() => renderWorkspaceDocs(unsafeWorkspace)).toThrow(/id/i);
|
|
});
|
|
|
|
test("v3 installation contract omits external vector and embedding bindings", () => {
|
|
const contract = buildInstallationContract(workspaceV3);
|
|
const names = contract.variables.map((variable) => variable.name);
|
|
|
|
expect(names).toContain("THT_WS_PSD_CLINICAL_DWH_TRANSPORT");
|
|
expect(names.some((name) => name.includes("_VECTOR_"))).toBe(false);
|
|
expect(names.some((name) => name.includes("_EMBEDDING_"))).toBe(false);
|
|
expect(renderWorkspaceDocs(workspaceV3).markdown).not.toContain("Embedding service");
|
|
});
|
|
|
|
|
|
test.each([
|
|
{
|
|
mode: "signed HTTP",
|
|
source: {
|
|
type: "http", uris: ["https://evidence.example.test/guide.md"],
|
|
authentication: "signed_urls_file",
|
|
},
|
|
expected: ["THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE"],
|
|
},
|
|
{
|
|
mode: "static S3",
|
|
source: { type: "s3", uri: "s3://clinical-evidence/published/", credentials: "static_files" },
|
|
expected: [
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_ACCESS_KEY_FILE",
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_SECRET_KEY_FILE",
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_SESSION_TOKEN_FILE",
|
|
],
|
|
},
|
|
])("generates source-specific $mode Evidence file bindings", ({ source, expected }) => {
|
|
const descriptor = parseWorkspaceYaml(`${renderWorkspaceWithoutEvidence()}evidence:\n source: ${JSON.stringify(source)}\n`);
|
|
const contract = buildInstallationContract(descriptor);
|
|
const evidence = contract.variables.filter((variable) => variable.role === "EVIDENCE");
|
|
|
|
expect(contract.namespace).toBe("PSD_CLINICAL");
|
|
expect(evidence.map((variable) => variable.name)).toEqual(expected);
|
|
expect(evidence.every((variable) => variable.secret)).toBe(true);
|
|
expect(renderWorkspaceDocs(descriptor).envExample).not.toContain("CANARY-SECRET");
|
|
});
|
|
|
|
test.each([
|
|
{ type: "filesystem", uri: "workspace-content/psd-clinical/evidence" },
|
|
{ type: "http", uris: ["https://evidence.example.test/guide.md"], authentication: "none" },
|
|
{ type: "s3", uri: "s3://clinical-evidence/published/", credentials: "ambient" },
|
|
])("omits Evidence installation variables for $type modes without file credentials", (source) => {
|
|
const descriptor = parseWorkspaceYaml(`${renderWorkspaceWithoutEvidence()}evidence:\n source: ${JSON.stringify(source)}\n`);
|
|
expect(buildInstallationContract(descriptor).variables.some((variable) => variable.role === "EVIDENCE"))
|
|
.toBe(false);
|
|
});
|
|
|
|
function renderWorkspaceWithoutEvidence(): string {
|
|
return `workspace:
|
|
schema_version: 3
|
|
id: psd-clinical
|
|
name: Policlinico San Donato
|
|
language: it
|
|
dwh:
|
|
engine: postgres
|
|
database: postgres
|
|
schema: datawarehouse
|
|
supported_transports: [postgres_direct]
|
|
semantic_index:
|
|
vector_store: { engine: qdrant, collection: psd-clinical, dimensions: 1024, distance: cosine }
|
|
embedding: { provider: ollama_internal, model: qwen3-embedding:0.6b, dimensions: 1024 }
|
|
llm_policy: { allowed: [zai/glm-5.2] }
|
|
`;
|
|
}
|
|
|
|
|
|
const evidenceSources = [
|
|
{
|
|
label: "filesystem",
|
|
source: { type: "filesystem", uri: "workspace-content/psd-clinical/evidence" },
|
|
variables: [],
|
|
},
|
|
{
|
|
label: "HTTP signed URL file",
|
|
source: {
|
|
type: "http",
|
|
uris: ["https://evidence.example.test/guide.md", "http://public.example.test/policy.pdf"],
|
|
authentication: "signed_urls_file",
|
|
},
|
|
variables: ["THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE"],
|
|
},
|
|
{
|
|
label: "S3 static files",
|
|
source: {
|
|
type: "s3", uri: "s3://clinical-evidence/published/", credentials: "static_files",
|
|
},
|
|
variables: [
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_ACCESS_KEY_FILE",
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_SECRET_KEY_FILE",
|
|
"THT_WS_PSD_CLINICAL_EVIDENCE_SESSION_TOKEN_FILE",
|
|
],
|
|
},
|
|
] as const;
|
|
|
|
test.each(evidenceSources)("renders deterministic public Evidence docs for $label", ({ source, variables }) => {
|
|
const descriptor = parseWorkspaceYaml(
|
|
`${renderWorkspaceWithoutEvidence()}evidence:\n source: ${JSON.stringify(source)}\n`,
|
|
);
|
|
const firstContract = buildInstallationContract(descriptor);
|
|
const secondContract = buildInstallationContract(descriptor);
|
|
const firstDocs = renderWorkspaceDocs(descriptor);
|
|
const secondDocs = renderWorkspaceDocs(descriptor);
|
|
|
|
expect(secondContract).toEqual(firstContract);
|
|
expect(secondDocs).toEqual(firstDocs);
|
|
expect(firstContract.variables.filter(({ role }) => role === "EVIDENCE").map(({ name }) => name))
|
|
.toEqual(variables);
|
|
expect(firstDocs.markdown).toContain("## Evidence source");
|
|
expect(firstDocs.markdown).toContain(`- Type: \`${source.type}\``);
|
|
for (const uri of "uris" in source ? source.uris : [source.uri]) {
|
|
expect(firstDocs.markdown).toContain(`\`${uri}\``);
|
|
}
|
|
expect(firstDocs.markdown).toContain("- Maximum source bytes: `10485760`");
|
|
expect(firstDocs.markdown).toContain("- Maximum chunk characters: `4000`");
|
|
expect(firstDocs.markdown).toContain("- Retained published generations: `3`");
|
|
for (const variable of variables) {
|
|
expect(firstDocs.markdown).toContain(`\`${variable}\``);
|
|
expect(firstDocs.envExample).toContain(`${variable}=`);
|
|
}
|
|
});
|
|
|
|
test("documents same-revision filesystem ownership without claiming P1 materialization", () => {
|
|
const descriptor = parseWorkspaceYaml(
|
|
`${renderWorkspaceWithoutEvidence()}evidence:\n source: { type: filesystem, uri: workspace-content/psd-clinical/evidence }\n`,
|
|
);
|
|
const docs = renderWorkspaceDocs(descriptor).markdown;
|
|
|
|
expect(docs).toContain("`workspace-content/psd-clinical/evidence`");
|
|
expect(docs).toMatch(/same Git revision/i);
|
|
expect(docs).toMatch(/P6.*materializ/i);
|
|
expect(docs).toMatch(/containment.*symlink/i);
|
|
expect(docs).toMatch(/does not include Evidence file bytes/i);
|
|
});
|
|
|
|
test.each([
|
|
{
|
|
source: { type: "http", uris: ["https://evidence.example.test/guide.md"], authentication: "none" },
|
|
expected: "No credential file is required",
|
|
},
|
|
{
|
|
source: { type: "http", uris: ["https://evidence.example.test/guide.md"], authentication: "signed_urls_file" },
|
|
expected: "signed URL file",
|
|
},
|
|
{
|
|
source: { type: "s3", uri: "s3://clinical-evidence/published/", credentials: "ambient" },
|
|
expected: "ambient credentials",
|
|
},
|
|
{
|
|
source: { type: "s3", uri: "s3://clinical-evidence/published/", credentials: "static_files" },
|
|
expected: "installation file variables",
|
|
},
|
|
])("documents $source.type credential mode without reading credential contents", ({ source, expected }) => {
|
|
const root = mkdtempSync(join(tmpdir(), "thoth-evidence-doc-secret-"));
|
|
const secrets = join(root, "secrets");
|
|
const canary = "CANARY-EVIDENCE-CREDENTIAL-DO-NOT-LEAK";
|
|
mkdirSync(secrets);
|
|
const binding = join(secrets, "credential");
|
|
writeFileSync(binding, canary);
|
|
const previous = process.env.THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE;
|
|
process.env.THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE = binding;
|
|
try {
|
|
const descriptor = parseWorkspaceYaml(
|
|
`${renderWorkspaceWithoutEvidence()}evidence:\n source: ${JSON.stringify(source)}\n`,
|
|
);
|
|
const generated = JSON.stringify({
|
|
contract: buildInstallationContract(descriptor),
|
|
docs: renderWorkspaceDocs(descriptor),
|
|
});
|
|
expect(generated).toContain(expected);
|
|
expect(generated).not.toContain(canary);
|
|
} finally {
|
|
if (previous === undefined) delete process.env.THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE;
|
|
else process.env.THT_WS_PSD_CLINICAL_EVIDENCE_SIGNED_URLS_FILE = previous;
|
|
rmSync(root, { recursive: true, force: true });
|
|
}
|
|
});
|