feat(cli): prepare and validate application documents offline

backend/test/database-bootstrap-documents.test.ts

@@ -0,0 +1,49 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, expect, test } from "vitest";
+import { validateDatabaseBootstrap } from "../src/catalog/bootstrap-documents.js";
+import { runBootstrapValidation } from "../src/catalog/bootstrap-cli.js";
+
+const roots: string[] = [];
+afterEach(() => roots.splice(0).forEach((root) => rmSync(root, { recursive: true, force: true })));
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), "bootstrap-documents-")); roots.push(root);
+  mkdirSync(join(root, "practice"));
+  writeFileSync(join(root, "thoth-workspaces.yaml"), "schema_version: 1\nworkspaces: [{id: practice, name: Practice}]\n");
+  writeFileSync(join(root, "practice/workspace.yaml"), "workspace: {schema_version: 4, id: practice, name: Practice, language: en}\n");
+  return root;
+}
+const entry = { workspaceId: "practice", engine: "postgres", databaseName: "practice", schema: "public", binding: { transport: "postgres_direct", host: "db.internal", port: 5432, username: "reader" }, secretFiles: { password: "/private/operator/db-password" } };
+
+test("bootstrap reuses Catalog configuration and requires one complete binding per workspace", () => {
+  const root = fixture();
+  const valid = validateDatabaseBootstrap({ schemaVersion: 1, databases: [entry] }, root);
+  expect(valid.secretFiles).toContainEqual({ field: "databases.0.secretFiles.password", path: "/private/operator/db-password" });
+  for (const databases of [[], [entry, entry], [{ ...entry, workspaceId: "unknown" }], [{ ...entry, secretFiles: {} }], [{ ...entry, engine: "mysql" }], [{ ...entry, binding: { ...entry.binding, port: 70000 } }]]) {
+    expect(() => validateDatabaseBootstrap({ schemaVersion: 1, databases }, root)).toThrow();
+  }
+});
+
+test("REST authentication, SSH credentials and optional Evidence use their declared contracts", () => {
+  const root = fixture();
+  const rest = { ...entry, binding: { transport: "rest_api", baseUrl: "https://data.internal", restPath: "/query", restAuth: "none" }, secretFiles: {} };
+  expect(validateDatabaseBootstrap({ schemaVersion: 1, databases: [rest] }, root).secretFiles).toEqual([]);
+  expect(() => validateDatabaseBootstrap({ schemaVersion: 1, databases: [{ ...rest, binding: { ...rest.binding, restAuth: "bearer" } }] }, root)).toThrow();
+  const ssh = { ...entry, binding: { transport: "ssh_tunnel", username: "reader", sshHost: "bastion", sshPort: 22, sshUsername: "tunnel", sshTargetHost: "database", sshTargetPort: 5432 }, secretFiles: { password: "/password", sshPrivateKey: "/key", sshKnownHosts: "/hosts" } };
+  expect(validateDatabaseBootstrap({ schemaVersion: 1, databases: [ssh] }, root).warnings[0]).toContain("not NL-to-SQL");
+  writeFileSync(join(root, "practice/workspace.yaml"), "workspace: {schema_version: 4, id: practice, name: Practice, language: en}\nevidence:\n  source:\n    type: http\n    uris: [https://docs.internal/manual.md]\n    authentication: signed_urls_file\n");
+  expect(() => validateDatabaseBootstrap({ schemaVersion: 1, databases: [entry] }, root)).toThrow();
+  expect(validateDatabaseBootstrap({ schemaVersion: 1, databases: [{ ...entry, evidenceSecretFiles: { "evidence.signed_urls": "/urls.json" } }] }, root).secretFiles).toContainEqual({ field: "databases.0.evidenceSecretFiles.evidence.signed_urls", path: "/urls.json" });
+});
+
+test("bootstrap CLI never echoes arbitrary keys from submitted secret references", () => {
+  const root = fixture();
+  const path = join(root, "bootstrap.yaml");
+  for (const field of ["secretFiles", "evidenceSecretFiles"]) {
+    writeFileSync(path, JSON.stringify({ schemaVersion: 1, databases: [{ ...entry, [field]: { PRIVATE_CREDENTIAL_SENTINEL: "/path" } }] }));
+    const result = runBootstrapValidation(["--directory", root, "--bootstrap", path, "--json"]);
+    expect(result.status).toBe(1);
+    expect(result.output).not.toContain("PRIVATE_CREDENTIAL_SENTINEL");
+  }
+});

backend/test/installation-documents-cli.test.ts

@@ -0,0 +1,67 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { rootCertificates } from "node:tls";
+import { afterEach, expect, test } from "vitest";
+
+const binary = process.env.THT_INSTALLATION_TEST_CLI;
+const roots: string[] = [];
+afterEach(() => roots.splice(0).forEach((path) => rmSync(path, { recursive: true, force: true })));
+function run(...args: string[]) {
+  return spawnSync(binary!, [...args, "--json"], { encoding: "utf8", env: { ...process.env, PATH: "" }, input: "" });
+}
+
+test.skipIf(!binary)("operator prepares, completes and repeatedly validates before any stack exists", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "application-documents-"))); roots.push(root);
+  const workspace = join(root, "workspaces"), directory = join(root, "installation");
+  expect(run("workspace", "prepare", "--directory", workspace, "--id", "practice", "--name", "Practice").status).toBe(0);
+  expect(run("installation", "prepare", "--directory", directory).status).toBe(0);
+  const installation = join(directory, "thothii-installation.yaml");
+  const validate = () => run("--installation", installation, "installation", "validate", "--workspaces", workspace);
+  expect(validate().status).toBe(1); // Visible placeholders cannot be approved.
+  expect(run("installation", "credentials", "--directory", directory).status).toBe(0);
+  for (const name of ["thothii-installation.yaml", "operator.env", "database-bootstrap.yaml"]) {
+    const path = join(directory, name);
+    writeFileSync(path, readFileSync(path, "utf8").replaceAll("CHANGE_ME", "practice"));
+  }
+  for (const [name, contents] of Object.entries({ "secrets.env": "OPENAI_API_KEY=PRIVATE_PROVIDER_VALUE\n", "database-password": "PRIVATE_DATABASE_VALUE", "git-credentials": "", "git-ca.pem": rootCertificates[0] })) {
+    writeFileSync(join(directory, "secrets", name), contents, { mode: 0o600 });
+  }
+  const before = readFileSync(installation, "utf8");
+  for (let index = 0; index < 2; index++) {
+    const checked = validate();
+    expect(checked.stderr).toBe("");
+    expect(checked.stdout).not.toContain("PRIVATE_");
+    expect(checked.status, checked.stdout).toBe(0);
+    expect(JSON.parse(checked.stdout).deferred_checks).toContain("release-assets");
+  }
+  expect(readFileSync(installation, "utf8")).toBe(before);
+  writeFileSync(installation, before.replace("interaction: openai/gpt-4.1-mini", "interaction: openai/nonexistent"));
+  expect(validate().status).toBe(1);
+  writeFileSync(installation, before);
+  const authFile = join(directory, "secrets/pi-auth.json");
+  writeFileSync(authFile, "not-json");
+  expect(validate().status).toBe(1);
+  writeFileSync(installation, before.replace("{mode: secret_env, apiKeyEnv: OPENAI_API_KEY}", "{mode: pi_auth}"));
+  writeFileSync(authFile, JSON.stringify({ openai: { unrelated: true } }));
+  expect(validate().status).toBe(1);
+  writeFileSync(authFile, JSON.stringify({ " OpenAI ": { type: "api_key", key: "PRIVATE_PI_KEY" } }));
+  expect(validate().status).toBe(1);
+  writeFileSync(authFile, JSON.stringify({ openai: { type: "api_key", key: "PRIVATE_PI_KEY" } }));
+  expect(validate().status).toBe(0);
+  writeFileSync(installation, before);
+  writeFileSync(authFile, "{}");
+  const bootstrap = join(directory, "database-bootstrap.yaml");
+  const originalBootstrap = readFileSync(bootstrap, "utf8");
+  writeFileSync(join(workspace, "practice", "private-password"), "PRIVATE_DATABASE_VALUE", { mode: 0o600 });
+  writeFileSync(bootstrap, originalBootstrap.replace(join(directory, "secrets/database-password"), join(workspace, "practice/private-password")));
+  expect(validate().status).toBe(1);
+  writeFileSync(bootstrap, originalBootstrap);
+  chmodSync(join(directory, "secrets/database-password"), 0o644);
+  expect(validate().status).toBe(1);
+  chmodSync(join(directory, "secrets/database-password"), 0o600);
+  const env = join(directory, "operator.env");
+  writeFileSync(env, readFileSync(env, "utf8") + "THOTH_HTTP_PORT=8081\n");
+  expect(validate().status).toBe(1);
+}, 15_000);