@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/profile/normalise.js

@@ -0,0 +1,106 @@
+import { isPlainObject } from "../case/util.js";
+export class ProfileShapeError extends Error {
+    constructor(message) {
+        super(`rhino-local: ${message}`);
+        this.name = "ProfileShapeError";
+    }
+}
+/**
+ * Normalise `GET /openidm/config/managed` into an `EnvProfile`.
+ *
+ * Pure, so the wire shape is testable without a tenant. Unknown keys are
+ * dropped rather than carried: this profile is consumed by validation, and a
+ * field nothing reads is a field that rots silently.
+ */
+export function normaliseManagedConfig(document, meta) {
+    if (!isPlainObject(document)) {
+        throw new ProfileShapeError("managed config is not an object");
+    }
+    const objects = document.objects;
+    if (!Array.isArray(objects)) {
+        throw new ProfileShapeError("managed config has no `objects` array");
+    }
+    const out = {};
+    for (const entry of objects) {
+        if (!isPlainObject(entry) || typeof entry.name !== "string") {
+            throw new ProfileShapeError("managed object entry has no `name`");
+        }
+        out[entry.name] = normaliseObject(entry.name, entry.schema);
+    }
+    return {
+        tenant: meta.tenant,
+        pulledAt: meta.pulledAt,
+        sources: [meta.endpoint],
+        objects: out,
+    };
+}
+function normaliseObject(name, schema) {
+    if (!isPlainObject(schema)) {
+        // An object with no schema block is real (some shipped types carry none).
+        // Record it as existing with no properties rather than dropping it: type
+        // EXISTENCE is what distinguishes an AIC `null` from a fixture typo, and
+        // that distinction must not depend on how richly the type is described.
+        return { name, properties: {}, required: [] };
+    }
+    const properties = {};
+    if (isPlainObject(schema.properties)) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            properties[key] = normaliseProperty(value);
+        }
+    }
+    const required = Array.isArray(schema.required)
+        ? schema.required.filter((item) => typeof item === "string")
+        : [];
+    return { name, properties, required };
+}
+function normaliseProperty(value) {
+    if (!isPlainObject(value)) {
+        return { type: "any" };
+    }
+    const { type, nullable } = normaliseType(value.type);
+    const out = { type };
+    if (nullable) {
+        out.nullable = true;
+    }
+    if (Array.isArray(value.enum)) {
+        out.enum = value.enum;
+    }
+    if (value.items !== undefined) {
+        out.items = normaliseProperty(value.items);
+    }
+    const targets = normaliseResourceCollection(value.resourceCollection);
+    if (targets.length > 0) {
+        out.resourceCollection = targets;
+    }
+    return out;
+}
+/**
+ * IDM spells a nullable scalar as `["string", "null"]`. Collapse that to one
+ * type plus a flag so no consumer has to re-derive it.
+ */
+function normaliseType(raw) {
+    if (typeof raw === "string") {
+        return { type: raw, nullable: false };
+    }
+    if (Array.isArray(raw)) {
+        const names = raw.filter((item) => typeof item === "string");
+        const concrete = names.filter((item) => item !== "null");
+        return {
+            type: concrete[0] ?? "any",
+            nullable: names.length !== concrete.length,
+        };
+    }
+    return { type: "any", nullable: false };
+}
+function normaliseResourceCollection(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const paths = [];
+    for (const entry of raw) {
+        if (isPlainObject(entry) && typeof entry.path === "string") {
+            paths.push(entry.path);
+        }
+    }
+    return paths;
+}

package/dist/src/profile/pull.d.ts

@@ -0,0 +1,22 @@
+import type { TenantProvider } from "../aic/provider.ts";
+import { type AicIo } from "../aic/tenant.ts";
+import type { EnvProfile } from "./types.ts";
+export declare const MANAGED_CONFIG_ENDPOINT = "/openidm/config/managed";
+export interface PullOptions {
+    tenant?: string;
+    project?: string;
+    /** Where the tenant and its bearer come from; see `resolveTenantProvider`. */
+    provider?: TenantProvider;
+    io?: AicIo;
+    now?: () => Date;
+}
+/**
+ * Pull one environment's managed-object schema into a normalised profile.
+ *
+ * One call covers every managed object the tenant defines, which is why this
+ * is worth more than per-object fixtures: the breadth comes free.
+ */
+export declare function pullProfile(options?: PullOptions): Promise<{
+    profile: EnvProfile;
+    path: string;
+}>;

package/dist/src/profile/pull.js

@@ -0,0 +1,36 @@
+import { AicLaneError, amRequest, connectTenant, defaultAicIo, } from "../aic/tenant.js";
+import { projectRoot } from "../project.js";
+import { normaliseManagedConfig } from "./normalise.js";
+import { writeProfile } from "./store.js";
+export const MANAGED_CONFIG_ENDPOINT = "/openidm/config/managed";
+/**
+ * Pull one environment's managed-object schema into a normalised profile.
+ *
+ * One call covers every managed object the tenant defines, which is why this
+ * is worth more than per-object fixtures: the breadth comes free.
+ */
+export async function pullProfile(options = {}) {
+    const project = options.project ?? projectRoot();
+    const io = options.io ?? defaultAicIo(project);
+    const session = await connectTenant(io, {
+        ...(options.tenant !== undefined ? { tenant: options.tenant } : {}),
+        ...(options.provider !== undefined ? { provider: options.provider } : {}),
+        useConfigured: options.io === undefined,
+        project,
+    });
+    const response = await amRequest(io, session, {
+        method: "GET",
+        path: MANAGED_CONFIG_ENDPOINT,
+    });
+    if (response.status !== 200) {
+        throw new AicLaneError(`GET ${MANAGED_CONFIG_ENDPOINT} returned ${response.status}: ${response.bodyText.slice(0, 300)}`, { status: response.status });
+    }
+    const now = (options.now ?? (() => new Date()))();
+    const profile = normaliseManagedConfig(response.body, {
+        tenant: session.tenantName,
+        pulledAt: now.toISOString(),
+        endpoint: MANAGED_CONFIG_ENDPOINT,
+    });
+    const path = writeProfile(profile);
+    return { profile, path };
+}

package/dist/src/profile/seed.d.ts

@@ -0,0 +1,11 @@
+import type { JsonObject } from "../case/types.ts";
+import type { EnvProfile } from "./types.ts";
+/**
+ * Strict-check every seeded managed record against the environment schema.
+ *
+ * Runs in Node before the case reaches the JVM, so a fixture typo is reported
+ * against the case that owns it. Records are checked in `seed` mode: property
+ * names and enum values must be real, but `required` is not demanded — a
+ * fixture legitimately carries only the fields the script under test reads.
+ */
+export declare function checkSeededManaged(profile: EnvProfile, managed: Record<string, JsonObject[]> | undefined, caseName: string): void;

package/dist/src/profile/seed.js

@@ -0,0 +1,28 @@
+import { checkRecord, SchemaViolation } from "./validate.js";
+/**
+ * Strict-check every seeded managed record against the environment schema.
+ *
+ * Runs in Node before the case reaches the JVM, so a fixture typo is reported
+ * against the case that owns it. Records are checked in `seed` mode: property
+ * names and enum values must be real, but `required` is not demanded — a
+ * fixture legitimately carries only the fields the script under test reads.
+ */
+export function checkSeededManaged(profile, managed, caseName) {
+    if (managed === undefined) {
+        return;
+    }
+    for (const [collection, rows] of Object.entries(managed)) {
+        for (const [index, row] of rows.entries()) {
+            const id = typeof row._id === "string" ? row._id : String(index);
+            try {
+                checkRecord(profile, `${collection}/${id}`, row, "seed");
+            }
+            catch (error) {
+                if (error instanceof SchemaViolation) {
+                    throw new SchemaViolation(error.kind, error.resource, `case ${JSON.stringify(caseName)}: given.managed[${JSON.stringify(collection)}][${index}]: ${error.message.replace(/^rhino-local: /, "")}`);
+                }
+                throw error;
+            }
+        }
+    }
+}

package/dist/src/profile/store.d.ts

@@ -0,0 +1,13 @@
+import type { EnvProfile } from "./types.ts";
+/**
+ * Profiles live in the harness state directory, which ignores itself.
+ * Managed object and property names are client business vocabulary, and the
+ * sensitive-metadata scanner deliberately holds no client-name denylist, so
+ * the guard is the location, not a filter.
+ */
+export declare function profilePath(tenant: string, root?: string): string;
+export declare function writeProfile(profile: EnvProfile, root?: string): string;
+export declare function readProfile(tenant: string, root?: string): EnvProfile;
+/** Read a profile if one exists; absent means "run without schema checking". */
+export declare function tryReadProfile(tenant: string, root?: string): EnvProfile | undefined;
+export declare function parseProfile(text: string, path: string): EnvProfile;

package/dist/src/profile/store.js

@@ -0,0 +1,60 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureStateSubdir, stateDir } from "../project.js";
+import { ProfileShapeError } from "./normalise.js";
+/**
+ * Profiles live in the harness state directory, which ignores itself.
+ * Managed object and property names are client business vocabulary, and the
+ * sensitive-metadata scanner deliberately holds no client-name denylist, so
+ * the guard is the location, not a filter.
+ */
+export function profilePath(tenant, root = stateDir()) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tenant)) {
+        throw new ProfileShapeError(`tenant name ${JSON.stringify(tenant)} cannot name a profile file`);
+    }
+    return join(root, "profiles", `${tenant}.json`);
+}
+export function writeProfile(profile, root = stateDir()) {
+    const path = profilePath(profile.tenant, root);
+    ensureStateSubdir(root, "profiles");
+    writeFileSync(path, `${JSON.stringify(profile, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    // `mode` applies only when the write creates the file.
+    chmodSync(path, 0o600);
+    return path;
+}
+export function readProfile(tenant, root = stateDir()) {
+    const path = profilePath(tenant, root);
+    if (!existsSync(path)) {
+        throw new ProfileShapeError(
+        // The tenant is not named: its name defaults to its hostname, and this
+        // surfaces in test output.
+        `no environment profile for this tenant in ${join(root, "profiles")}. Pull one: aic-script-tester-pull-profile`);
+    }
+    return parseProfile(readFileSync(path, "utf8"), path);
+}
+/** Read a profile if one exists; absent means "run without schema checking". */
+export function tryReadProfile(tenant, root = stateDir()) {
+    return existsSync(profilePath(tenant, root))
+        ? readProfile(tenant, root)
+        : undefined;
+}
+export function parseProfile(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProfileShapeError(`profile at ${path} is not JSON: ${message}`);
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.tenant !== "string" ||
+        typeof parsed.objects !== "object") {
+        throw new ProfileShapeError(`profile at ${path} is missing tenant/objects`);
+    }
+    return parsed;
+}

package/dist/src/profile/types.d.ts

@@ -0,0 +1,45 @@
+import type { JsonValue } from "../case/types.ts";
+/**
+ * A normalised snapshot of one environment's managed-object schema.
+ *
+ * Deliberately NOT the raw `/openidm/config/managed` document. That document
+ * carries lifecycle hook SOURCE BODIES, which are client code, and a great deal
+ * of UI metadata (`viewable`, `searchable`, `iconClass`, `order`) that no
+ * validation here consults. Normalising keeps the artefact small enough to read
+ * in a diff and drops the two things we must not accumulate: script source and
+ * presentation noise.
+ *
+ * Lives under `workspace/<tenant>/`, which `.gitignore` covers in full — object
+ * and property names are client business vocabulary.
+ */
+export interface EnvProfile {
+    /** Tenant context name, as `aic ctx list` reports it. Never a hostname. */
+    tenant: string;
+    /** ISO-8601. Staleness is the operator's call; nothing here expires. */
+    pulledAt: string;
+    /** Endpoints this profile was built from, for the audit trail. */
+    sources: string[];
+    /** Keyed by managed object name, e.g. `alpha_user`. */
+    objects: Record<string, ObjectSchema>;
+}
+export interface ObjectSchema {
+    name: string;
+    properties: Record<string, PropertySchema>;
+    /** Property names IDM rejects a create without. */
+    required: string[];
+}
+export interface PropertySchema {
+    /**
+     * Normalised JSON-schema type. IDM writes `["string","null"]` for a nullable
+     * scalar; that becomes `type: "string"` plus `nullable: true`, so every
+     * consumer sees one spelling.
+     */
+    type: string;
+    nullable?: boolean;
+    /** Present only on an enum-constrained scalar. AIC enforces this on write. */
+    enum?: JsonValue[];
+    /** Element schema for `type: "array"`. */
+    items?: PropertySchema;
+    /** `managed/<target>` paths, for `type: "relationship"`. */
+    resourceCollection?: string[];
+}

package/dist/src/profile/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/profile/validate.d.ts

@@ -0,0 +1,38 @@
+import type { JsonObject } from "../case/types.ts";
+import type { EnvProfile, ObjectSchema } from "./types.ts";
+export declare class SchemaViolation extends Error {
+    readonly kind: "unknown-type" | "unknown-property" | "missing-required" | "bad-enum";
+    readonly resource: string;
+    constructor(kind: SchemaViolation["kind"], resource: string, message: string);
+}
+/** `managed/alpha_user/alice` -> `{ type: "managed/alpha_user", id: "alice" }`. */
+export declare function splitResource(resource: string): {
+    type: string;
+    id?: string;
+};
+/** Object name for a `managed/<name>` resource, or undefined for other containers. */
+export declare function managedObjectName(resourceType: string): string | undefined;
+/**
+ * Does this environment define the object type behind `resource`?
+ *
+ * This is the whole reason a profile is worth pulling. Without one, the harness
+ * cannot tell "the tenant has this type and the record is simply absent"
+ * (AIC returns `null`) from "this type does not exist and your fixture has a
+ * typo" (AIC also returns `null`, unhelpfully). With one, the two become
+ * distinguishable locally, and only the second is worth failing on.
+ */
+export declare function knowsType(profile: EnvProfile, resource: string): boolean;
+export declare function objectFor(profile: EnvProfile, resource: string): ObjectSchema | undefined;
+/** Names a type that is not in the profile, listing near misses. */
+export declare function unknownTypeError(profile: EnvProfile, resource: string): SchemaViolation;
+/**
+ * Strict check of a record's properties against the object schema.
+ *
+ * `mode` picks which half of the rule applies. A seeded fixture is checked for
+ * property existence only — it stands in for a record the tenant already holds,
+ * and demanding `required` of it would reject every partial fixture. A write is
+ * checked for `required` too, because that is what AIC enforces on create.
+ */
+export declare function checkRecord(profile: EnvProfile, resource: string, record: JsonObject, mode: "seed" | "create" | "patch"): void;
+/** True when `value` is a plain record we can check. */
+export declare function isRecord(value: unknown): value is JsonObject;

package/dist/src/profile/validate.js

@@ -0,0 +1,129 @@
+import { isPlainObject } from "../case/util.js";
+/**
+ * CREST metadata every managed record carries regardless of the declared
+ * schema. Allowed unconditionally so strict property checking does not reject
+ * a record the tenant itself would return.
+ */
+const CREST_META = new Set(["_id", "_rev", "_meta", "_ref", "_refProperties"]);
+export class SchemaViolation extends Error {
+    kind;
+    resource;
+    constructor(kind, resource, message) {
+        super(`rhino-local: ${message}`);
+        this.name = "SchemaViolation";
+        this.kind = kind;
+        this.resource = resource;
+    }
+}
+/** `managed/alpha_user/alice` -> `{ type: "managed/alpha_user", id: "alice" }`. */
+export function splitResource(resource) {
+    const parts = resource.split("/").filter((part) => part.length > 0);
+    if (parts.length >= 3) {
+        return { type: `${parts[0]}/${parts[1]}`, id: parts.slice(2).join("/") };
+    }
+    return { type: parts.join("/") };
+}
+/** Object name for a `managed/<name>` resource, or undefined for other containers. */
+export function managedObjectName(resourceType) {
+    const [container, name] = resourceType.split("/");
+    return container === "managed" && name !== undefined && name.length > 0
+        ? name
+        : undefined;
+}
+/**
+ * Does this environment define the object type behind `resource`?
+ *
+ * This is the whole reason a profile is worth pulling. Without one, the harness
+ * cannot tell "the tenant has this type and the record is simply absent"
+ * (AIC returns `null`) from "this type does not exist and your fixture has a
+ * typo" (AIC also returns `null`, unhelpfully). With one, the two become
+ * distinguishable locally, and only the second is worth failing on.
+ */
+export function knowsType(profile, resource) {
+    const { type } = splitResource(resource);
+    const name = managedObjectName(type);
+    return name !== undefined && Object.hasOwn(profile.objects, name);
+}
+export function objectFor(profile, resource) {
+    const name = managedObjectName(splitResource(resource).type);
+    return name === undefined ? undefined : profile.objects[name];
+}
+/** Names a type that is not in the profile, listing near misses. */
+export function unknownTypeError(profile, resource) {
+    const { type } = splitResource(resource);
+    const name = managedObjectName(type);
+    const known = Object.keys(profile.objects).sort();
+    const near = name === undefined ? [] : known.filter((candidate) => close(candidate, name));
+    const hint = near.length > 0
+        ? ` Did you mean ${near.map((item) => `managed/${item}`).join(", ")}?`
+        : ` This environment defines ${known.length} managed object${known.length === 1 ? "" : "s"}.`;
+    return new SchemaViolation("unknown-type", resource, `openidm: ${JSON.stringify(type)} is not a managed object in environment ${JSON.stringify(profile.tenant)}.${hint}`);
+}
+/** Cheap near-miss test: shared prefix, or one edit apart in length. */
+function close(candidate, name) {
+    const a = candidate.toLowerCase();
+    const b = name.toLowerCase();
+    if (a === b) {
+        return true;
+    }
+    if (a.startsWith(b) || b.startsWith(a)) {
+        return true;
+    }
+    return Math.abs(a.length - b.length) <= 1 && sharedPrefix(a, b) >= a.length - 2;
+}
+function sharedPrefix(a, b) {
+    let index = 0;
+    while (index < a.length && index < b.length && a[index] === b[index]) {
+        index += 1;
+    }
+    return index;
+}
+/**
+ * Strict check of a record's properties against the object schema.
+ *
+ * `mode` picks which half of the rule applies. A seeded fixture is checked for
+ * property existence only — it stands in for a record the tenant already holds,
+ * and demanding `required` of it would reject every partial fixture. A write is
+ * checked for `required` too, because that is what AIC enforces on create.
+ */
+export function checkRecord(profile, resource, record, mode) {
+    const schema = objectFor(profile, resource);
+    if (schema === undefined) {
+        throw unknownTypeError(profile, resource);
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (CREST_META.has(key)) {
+            continue;
+        }
+        const property = schema.properties[key];
+        if (property === undefined) {
+            throw new SchemaViolation("unknown-property", resource, `openidm: ${JSON.stringify(key)} is not a property of managed/${schema.name} in environment ${JSON.stringify(profile.tenant)}.`);
+        }
+        checkEnum(resource, schema.name, key, property.enum, value);
+        if (property.items?.enum !== undefined && Array.isArray(value)) {
+            for (const element of value) {
+                checkEnum(resource, schema.name, `${key}[]`, property.items.enum, element);
+            }
+        }
+    }
+    if (mode === "create") {
+        for (const key of schema.required) {
+            if (!Object.hasOwn(record, key)) {
+                throw new SchemaViolation("missing-required", resource, `openidm: managed/${schema.name} requires ${JSON.stringify(key)}; AIC rejects a create without it.`);
+            }
+        }
+    }
+}
+function checkEnum(resource, objectName, key, allowed, value) {
+    if (allowed === undefined || value === null || value === undefined) {
+        return;
+    }
+    if (allowed.some((candidate) => candidate === value)) {
+        return;
+    }
+    throw new SchemaViolation("bad-enum", resource, `openidm: ${JSON.stringify(value)} is not an allowed value for managed/${objectName}.${key} (allowed: ${allowed.map((item) => JSON.stringify(item)).join(", ")}).`);
+}
+/** True when `value` is a plain record we can check. */
+export function isRecord(value) {
+    return isPlainObject(value);
+}

package/dist/src/project.d.ts

@@ -0,0 +1,37 @@
+/** Overrides {@link projectRoot}. */
+export declare const PROJECT_ENV = "AIC_SCRIPT_TESTER_PROJECT";
+/** Overrides {@link stateDir}. */
+export declare const STATE_DIR_ENV = "AIC_SCRIPT_TESTER_STATE_DIR";
+/**
+ * The project the harness is running for: `AIC_SCRIPT_TESTER_PROJECT`, else the
+ * nearest ancestor of the working directory holding `.git` (a directory, or
+ * the file a worktree has), else the working directory.
+ *
+ * Not the package's own location — installed, that is inside
+ * `node_modules`, and nothing the harness writes belongs there.
+ */
+export declare function projectRoot(env?: NodeJS.ProcessEnv, cwd?: string): string;
+/**
+ * Where the harness keeps per-project state: failure dumps, show-log views,
+ * environment profiles. `AIC_SCRIPT_TESTER_STATE_DIR`, else
+ * `<project>/.aic-script-tester`.
+ */
+export declare function stateDir(env?: NodeJS.ProcessEnv, cwd?: string): string;
+/**
+ * Create `dir` (under the state directory) and make sure the state directory
+ * ignores itself. Everything in it can name a live tenant — log bodies,
+ * hostnames, managed-object vocabulary — and a consuming repo's `.gitignore`
+ * knows nothing about it, so the guard travels with the directory rather than
+ * relying on the host repo (the same move as `src/backup.rs`).
+ */
+export declare function ensureStateSubdir(root: string, ...parts: string[]): string;
+/**
+ * `<state>/failures/failures.jsonl`. `create` makes the directory (and the
+ * state directory's `.gitignore`); a read does not.
+ */
+export declare function failuresPath(options?: {
+    create?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/** `<state>/failures/latest-logs.json`, the view `show-log` opens. */
+export declare function latestLogsPath(env?: NodeJS.ProcessEnv): string;

package/dist/src/project.js

@@ -0,0 +1,93 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** Overrides {@link projectRoot}. */
+export const PROJECT_ENV = "AIC_SCRIPT_TESTER_PROJECT";
+/** Overrides {@link stateDir}. */
+export const STATE_DIR_ENV = "AIC_SCRIPT_TESTER_STATE_DIR";
+/**
+ * The project the harness is running for: `AIC_SCRIPT_TESTER_PROJECT`, else the
+ * nearest ancestor of the working directory holding `.git` (a directory, or
+ * the file a worktree has), else the working directory.
+ *
+ * Not the package's own location — installed, that is inside
+ * `node_modules`, and nothing the harness writes belongs there.
+ */
+export function projectRoot(env = process.env, cwd = process.cwd()) {
+    const configured = env[PROJECT_ENV];
+    if (configured !== undefined && configured !== "") {
+        return resolve(configured);
+    }
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, ".git"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return resolve(cwd);
+        }
+        dir = parent;
+    }
+}
+/**
+ * Where the harness keeps per-project state: failure dumps, show-log views,
+ * environment profiles. `AIC_SCRIPT_TESTER_STATE_DIR`, else
+ * `<project>/.aic-script-tester`.
+ */
+export function stateDir(env = process.env, cwd) {
+    const configured = env[STATE_DIR_ENV];
+    if (configured !== undefined && configured !== "") {
+        return resolve(configured);
+    }
+    return join(projectRoot(env, cwd), ".aic-script-tester");
+}
+/**
+ * Create `dir` (under the state directory) and make sure the state directory
+ * ignores itself. Everything in it can name a live tenant — log bodies,
+ * hostnames, managed-object vocabulary — and a consuming repo's `.gitignore`
+ * knows nothing about it, so the guard travels with the directory rather than
+ * relying on the host repo (the same move as `src/backup.rs`).
+ */
+export function ensureStateSubdir(root, ...parts) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const ignore = join(root, ".gitignore");
+    if (!existsSync(ignore)) {
+        try {
+            writeFileSync(ignore, "*\n", { encoding: "utf8", flag: "wx" });
+        }
+        catch (error) {
+            // A concurrent writer got there first; its file says the same thing.
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    // An existing file is only trusted if it still ignores everything: one
+    // edited down, or with a `!` re-include after the `*`, would let the next
+    // profile or log dump be committed. The last matching rule wins, so a
+    // trailing `*` restores the guarantee whatever came before it.
+    const text = readFileSync(ignore, "utf8");
+    const rules = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== "" && !line.startsWith("#"));
+    if (rules.at(-1) !== "*") {
+        appendFileSync(ignore, `${text === "" || text.endsWith("\n") ? "" : "\n"}*\n`);
+    }
+    const dir = join(root, ...parts);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/**
+ * `<state>/failures/failures.jsonl`. `create` makes the directory (and the
+ * state directory's `.gitignore`); a read does not.
+ */
+export function failuresPath(options = {}) {
+    const root = stateDir(options.env);
+    const dir = options.create === true ? ensureStateSubdir(root, "failures") : join(root, "failures");
+    return join(dir, "failures.jsonl");
+}
+/** `<state>/failures/latest-logs.json`, the view `show-log` opens. */
+export function latestLogsPath(env = process.env) {
+    return join(ensureStateSubdir(stateDir(env), "failures"), "latest-logs.json");
+}