primitive-admin 1.0.61 → 1.0.63

package/dist/src/lib/integration-request-config.js

@@ -0,0 +1,145 @@
+/**
+ * The CLI's mirror of the server's integration `requestConfig` normalization
+ * (issue #2880, DSO-003).
+ *
+ * `normalizeIntegrationRequestConfig` (`src/services/integration-utils.ts`)
+ * rewrites an accepted request config on the way in: the base URL gains a
+ * single trailing slash, methods are upper-cased and de-duplicated, header and
+ * query lists are trimmed, and the optional keys are materialized. So the state
+ * the server RETURNS is not the text a hand-authored file holds — and comparing
+ * the two raw makes an authored integration read `local-edited` on every run,
+ * with push re-applying the same update forever. Baseline restamping cannot
+ * save it: after an apply the remote hash equals the fresh baseline while the
+ * local hash still does not.
+ *
+ * Mirrored rather than imported: the published CLI must not import server
+ * `src/` at runtime (the same rule the vendored config surfaces follow). The
+ * acceptance fixture pinning this mirror is the tripwire if the server's rule
+ * moves — a disagreement then shows as an ordinary `Modified` row, never a
+ * crash, which is why every step here is total: an input the server would
+ * REJECT (a missing base URL, a bogus method) is left exactly as authored so
+ * the server's own error is what the operator sees.
+ */
+/** Trim, drop empties, optionally re-case, and de-duplicate. */
+function normalizeStringList(value, { lowercase = false, uppercase = false } = {}) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            continue;
+        let normalized = item.trim();
+        if (!normalized)
+            continue;
+        if (lowercase)
+            normalized = normalized.toLowerCase();
+        if (uppercase)
+            normalized = normalized.toUpperCase();
+        out.push(normalized);
+    }
+    return [...new Set(out)];
+}
+/** `https://host/v1///` → `https://host/v1/`; anything else stays as authored. */
+function canonicalBaseUrl(raw) {
+    if (typeof raw !== "string")
+        return raw;
+    const base = raw.trim();
+    if (!(base.startsWith("http://") ||
+        base.startsWith("https://") ||
+        base.startsWith("test://"))) {
+        // The server rejects this; leaving it alone keeps the rejection the
+        // server's to make and the difference visible in the meantime.
+        return base;
+    }
+    return `${base.replace(/\/+$/, "")}/`;
+}
+/**
+ * The request config as the server would store it, from what the file says.
+ *
+ * Applied to BOTH sides of the comparison (the remote side reaches it through
+ * the same projection), which is safe because the server's own output is
+ * already canonical and this is idempotent.
+ */
+export function canonicalizeIntegrationRequestConfig(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return input;
+    const raw = input;
+    const allowedMethods = normalizeStringList(raw.allowedMethods, {
+        uppercase: true,
+    });
+    const defaultMethod = raw.defaultMethod
+        ? String(raw.defaultMethod).toUpperCase()
+        : allowedMethods[0] || "GET";
+    const methods = allowedMethods.length > 0 ? allowedMethods : ["GET"];
+    if (!methods.includes(defaultMethod))
+        methods.push(defaultMethod);
+    const allowedPaths = normalizeStringList(raw.allowedPaths).map((path) => path === "*" ? "/*" : path);
+    const defaultHeaders = {};
+    if (raw.defaultHeaders && typeof raw.defaultHeaders === "object") {
+        for (const [key, value] of Object.entries(raw.defaultHeaders)) {
+            if (!key)
+                continue;
+            defaultHeaders[key] = value == null ? "" : String(value);
+        }
+    }
+    const staticQuery = {};
+    if (raw.staticQuery && typeof raw.staticQuery === "object") {
+        for (const [key, value] of Object.entries(raw.staticQuery)) {
+            if (!key)
+                continue;
+            if (typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean") {
+                staticQuery[key] = value;
+            }
+        }
+    }
+    const validBodyModes = ["json", "raw", "multipart"];
+    const bodyMode = validBodyModes.includes(raw.bodyMode)
+        ? raw.bodyMode
+        : undefined;
+    let multipartFieldMapping;
+    if (Array.isArray(raw.multipartFieldMapping)) {
+        multipartFieldMapping = raw.multipartFieldMapping
+            .filter((f) => f &&
+            typeof f === "object" &&
+            typeof f.fieldName === "string" &&
+            (f.type === "attachment" || f.type === "value"))
+            .map((f) => ({
+            fieldName: f.fieldName,
+            type: f.type,
+            ...(f.attachmentIndex !== undefined && {
+                attachmentIndex: f.attachmentIndex,
+            }),
+            ...(f.attachmentName !== undefined && {
+                attachmentName: f.attachmentName,
+            }),
+            ...(f.value !== undefined && { value: f.value }),
+        }));
+        if (multipartFieldMapping.length === 0)
+            multipartFieldMapping = undefined;
+    }
+    return {
+        baseUrl: canonicalBaseUrl(raw.baseUrl),
+        allowedMethods: methods,
+        allowedPaths: allowedPaths.length > 0 ? allowedPaths : ["/*"],
+        defaultMethod,
+        defaultHeaders,
+        forwardHeaders: normalizeStringList(raw.forwardHeaders, {
+            lowercase: true,
+        }),
+        staticQuery,
+        forwardQueryParams: normalizeStringList(raw.forwardQueryParams, {
+            lowercase: true,
+        }),
+        // The server stores `true` unless the value is exactly `false`.
+        responsePassthrough: raw.responsePassthrough === false ? false : true,
+        ...(raw.exampleQuery && typeof raw.exampleQuery === "object"
+            ? { exampleQuery: raw.exampleQuery }
+            : {}),
+        ...(raw.exampleBody !== undefined ? { exampleBody: raw.exampleBody } : {}),
+        ...(bodyMode ? { bodyMode } : {}),
+        ...(multipartFieldMapping ? { multipartFieldMapping } : {}),
+    };
+}
+//# sourceMappingURL=integration-request-config.js.map

package/dist/src/lib/integration-request-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-request-config.js","sourceRoot":"","sources":["../../../src/lib/integration-request-config.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/integration-selector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the identifier the `integrations tests` verbs take (issue #3000).
+ *
+ * The block-testing endpoints key on the composite `integration#<blockId>` and
+ * never check that the block exists, so an identifier that names no
+ * integration came back as an empty page rather than a 404: `tests list`
+ * printed "No test cases found." and `tests run-all` printed
+ * `Total Tests: 0 / Failed: 0` and exited 0. That is success-shaped in CI and
+ * indistinguishable from an integration that genuinely has no cases, so a
+ * typo, an integration KEY, or an ID from another app all read as "nothing to
+ * run".
+ *
+ * Resolving here — against the app's own integration list — is what makes
+ * `Total Tests: 0` mean "this integration exists and has no cases". The list
+ * is the one call that can answer both halves: it maps a key to its ID (keys
+ * are stored lowercased, so the match is case-insensitive) and it proves the
+ * identifier belongs to THIS app. Archived integrations are included, because
+ * their cases stay inspectable.
+ */
+export interface ResolvedIntegration {
+    integrationId: string;
+    /** The integration's key, when the summary carries one. */
+    integrationKey?: string;
+}
+/** The one method this resolver needs from `ApiClient`. */
+export interface IntegrationLister {
+    listIntegrations(appId: string, params?: {
+        status?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+}
+/**
+ * Map an integration ID or key to its integration ID.
+ *
+ * Throws — naming the identifier — when nothing in the app matches, so the
+ * caller's existing catch prints the message and exits non-zero.
+ */
+export declare function resolveIntegrationSelector(client: IntegrationLister, appId: string, selector: string): Promise<ResolvedIntegration>;

package/dist/src/lib/integration-selector.js

@@ -0,0 +1,46 @@
+/**
+ * Resolve the identifier the `integrations tests` verbs take (issue #3000).
+ *
+ * The block-testing endpoints key on the composite `integration#<blockId>` and
+ * never check that the block exists, so an identifier that names no
+ * integration came back as an empty page rather than a 404: `tests list`
+ * printed "No test cases found." and `tests run-all` printed
+ * `Total Tests: 0 / Failed: 0` and exited 0. That is success-shaped in CI and
+ * indistinguishable from an integration that genuinely has no cases, so a
+ * typo, an integration KEY, or an ID from another app all read as "nothing to
+ * run".
+ *
+ * Resolving here — against the app's own integration list — is what makes
+ * `Total Tests: 0` mean "this integration exists and has no cases". The list
+ * is the one call that can answer both halves: it maps a key to its ID (keys
+ * are stored lowercased, so the match is case-insensitive) and it proves the
+ * identifier belongs to THIS app. Archived integrations are included, because
+ * their cases stay inspectable.
+ */
+import { paginateAll } from "./paginate.js";
+/**
+ * Map an integration ID or key to its integration ID.
+ *
+ * Throws — naming the identifier — when nothing in the app matches, so the
+ * caller's existing catch prints the message and exits non-zero.
+ */
+export async function resolveIntegrationSelector(client, appId, selector) {
+    const identifier = (selector ?? "").trim();
+    if (!identifier) {
+        throw new Error("An integration ID or key is required.");
+    }
+    const items = await paginateAll((cursor) => client.listIntegrations(appId, cursor ? { cursor } : {}));
+    const lowered = identifier.toLowerCase();
+    const match = items.find((item) => item?.integrationId === identifier) ??
+        items.find((item) => typeof item?.integrationKey === "string" &&
+            item.integrationKey.toLowerCase() === lowered);
+    if (!match) {
+        throw new Error(`No integration '${identifier}' in app ${appId}. ` +
+            `Pass an integration key or ID from 'primitive integrations list'.`);
+    }
+    return {
+        integrationId: match.integrationId ?? identifier,
+        ...(match.integrationKey ? { integrationKey: match.integrationKey } : {}),
+    };
+}
+//# sourceMappingURL=integration-selector.js.map

package/dist/src/lib/integration-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration-selector.js","sourceRoot":"","sources":["../../../src/lib/integration-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAgB5C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAyB,EACzB,KAAa,EACb,QAAgB;IAEhB,MAAM,UAAU,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,WAAW,CAAM,CAAC,MAAM,EAAE,EAAE,CAC9C,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACzD,CAAC;IAEF,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACzC,MAAM,KAAK,GACT,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;QACxD,KAAK,CAAC,IAAI,CACR,CAAC,IAAI,EAAE,EAAE,CACP,OAAO,IAAI,EAAE,cAAc,KAAK,QAAQ;YACxC,IAAI,CAAC,cAAc,CAAC,WAAW,EAAE,KAAK,OAAO,CAChD,CAAC;IAEJ,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,mBAAmB,UAAU,YAAY,KAAK,IAAI;YAChD,mEAAmE,CACtE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,UAAU;QAChD,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC"}

package/dist/src/lib/local-state.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-machine Primitive state: `.primitive/local.json` (#2873).
+ *
+ * `primitive env use` records which environment THIS machine is pointed at.
+ * That is not a team decision, so it must not land in the committed
+ * `.primitive/config.json` — `defaultEnvironment` stays the team default a
+ * fresh clone resolves. The file sits beside `credentials.json`, which has the
+ * same "local, never committed" property.
+ *
+ * Reads go through the shared core (`env-resolver-core.ts`) so every reader —
+ * CLI, Vite plugin, Swift script — agrees; this module owns the writes and the
+ * ignore coverage that keeps the file out of `git status`.
+ */
+import { localStatePathForConfigPath, readLocalSelection } from "./env-resolver-core.js";
+export { localStatePathForConfigPath, readLocalSelection };
+/**
+ * Writes this machine's environment selection. Returns the path written so
+ * callers can name it in their success message.
+ */
+export declare function writeLocalSelection(configPath: string, name: string): string;
+/**
+ * Clears the selection if (and only if) it names `name`. Used by `env remove`
+ * so removing the selected environment can't leave a dangling selection that
+ * makes every later command fail.
+ */
+export declare function clearLocalSelection(configPath: string, name: string): boolean;
+export interface IgnoreCoverageOutcome {
+    /**
+     * - `not-a-repo`     — nothing to do; the file cannot show up in a diff.
+     * - `already-ignored`— a committed .gitignore (or an earlier exclude) covers it.
+     * - `excluded`       — we appended a pattern to the repo's info/exclude file.
+     * - `failed`         — git was unavailable or the write failed; caller warns.
+     */
+    status: "not-a-repo" | "already-ignored" | "excluded" | "failed";
+    /** The exclude file written, for `excluded`. */
+    excludePath?: string;
+    /** The pattern written, for `excluded`. */
+    pattern?: string;
+    /** Why, for `failed`. */
+    detail?: string;
+}
+/**
+ * Makes sure `.primitive/local.json` is ignored before it is written.
+ *
+ * Templates scaffolded from now on carry the entry in their `.gitignore`, but
+ * projects created before this change do not — and `env use` writing an
+ * untracked-but-committable file would be exactly the "switching backends
+ * dirties the repo" problem this replaced. When the file is not already
+ * covered we append an anchored pattern to the repository's exclude file,
+ * resolved via `git rev-parse --git-path info/exclude` so a linked worktree
+ * (where `.git` is a FILE) works, and anchored relative to
+ * `git rev-parse --show-toplevel` so a project root nested below the worktree
+ * root is not mis-rooted.
+ */
+export declare function ensureLocalStateIgnored(localStatePath: string): IgnoreCoverageOutcome;

package/dist/src/lib/local-state.js

@@ -0,0 +1,167 @@
+/**
+ * Per-machine Primitive state: `.primitive/local.json` (#2873).
+ *
+ * `primitive env use` records which environment THIS machine is pointed at.
+ * That is not a team decision, so it must not land in the committed
+ * `.primitive/config.json` — `defaultEnvironment` stays the team default a
+ * fresh clone resolves. The file sits beside `credentials.json`, which has the
+ * same "local, never committed" property.
+ *
+ * Reads go through the shared core (`env-resolver-core.ts`) so every reader —
+ * CLI, Vite plugin, Swift script — agrees; this module owns the writes and the
+ * ignore coverage that keeps the file out of `git status`.
+ */
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative, sep } from "path";
+import { PRIMITIVE_LOCAL_STATE_VERSION, localStatePathForConfigPath, readLocalSelection, } from "./env-resolver-core.js";
+export { localStatePathForConfigPath, readLocalSelection };
+/**
+ * Writes this machine's environment selection. Returns the path written so
+ * callers can name it in their success message.
+ */
+export function writeLocalSelection(configPath, name) {
+    const path = localStatePathForConfigPath(configPath);
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // Preserve any unrelated keys a future version of the CLI may have written.
+    let existing = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            // A corrupt file is replaced wholesale — that is exactly the remedy the
+            // corrupt-local-state error tells the user to reach for.
+        }
+    }
+    const body = {
+        ...existing,
+        version: PRIMITIVE_LOCAL_STATE_VERSION,
+        selectedEnvironment: name,
+    };
+    writeFileSync(path, JSON.stringify(body, null, 2) + "\n");
+    return path;
+}
+/**
+ * Clears the selection if (and only if) it names `name`. Used by `env remove`
+ * so removing the selected environment can't leave a dangling selection that
+ * makes every later command fail.
+ */
+export function clearLocalSelection(configPath, name) {
+    const path = localStatePathForConfigPath(configPath);
+    if (!existsSync(path))
+        return false;
+    let current;
+    try {
+        current = readLocalSelection(configPath);
+    }
+    catch {
+        // Corrupt local state: nothing to match against, and rewriting it here
+        // would swallow an error the user should see from a resolution instead.
+        return false;
+    }
+    if (current !== name)
+        return false;
+    let existing = {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            existing = parsed;
+        }
+    }
+    catch {
+        return false;
+    }
+    delete existing.selectedEnvironment;
+    writeFileSync(path, JSON.stringify({ version: PRIMITIVE_LOCAL_STATE_VERSION, ...existing }, null, 2) + "\n");
+    return true;
+}
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+/**
+ * Escapes a path segment for use in a gitignore pattern. `*`, `?`, `[`, `]`
+ * and `\` are pattern syntax; `#` and `!` are line-leading syntax. Anchoring
+ * the pattern with a leading `/` (done by the caller) is what makes it
+ * relative to the repository root rather than "any directory named this".
+ */
+function escapeGitignorePattern(relPath) {
+    return relPath.replace(/[\\*?[\]]/g, (c) => "\\" + c).replace(/^([#!])/, "\\$1");
+}
+/**
+ * Makes sure `.primitive/local.json` is ignored before it is written.
+ *
+ * Templates scaffolded from now on carry the entry in their `.gitignore`, but
+ * projects created before this change do not — and `env use` writing an
+ * untracked-but-committable file would be exactly the "switching backends
+ * dirties the repo" problem this replaced. When the file is not already
+ * covered we append an anchored pattern to the repository's exclude file,
+ * resolved via `git rev-parse --git-path info/exclude` so a linked worktree
+ * (where `.git` is a FILE) works, and anchored relative to
+ * `git rev-parse --show-toplevel` so a project root nested below the worktree
+ * root is not mis-rooted.
+ */
+export function ensureLocalStateIgnored(localStatePath) {
+    const dir = dirname(localStatePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    let topLevel;
+    try {
+        topLevel = git(dir, ["rev-parse", "--show-toplevel"]);
+    }
+    catch {
+        return { status: "not-a-repo" };
+    }
+    if (!topLevel)
+        return { status: "not-a-repo" };
+    try {
+        execFileSync("git", ["check-ignore", "-q", "--", localStatePath], {
+            cwd: dir,
+            stdio: "ignore",
+        });
+        return { status: "already-ignored" };
+    }
+    catch {
+        // Exit 1 means "not ignored" — carry on and add coverage.
+    }
+    // git reports the toplevel with symlinks resolved (/private/var on macOS);
+    // the caller's path usually is not (/var). Compare like for like or the
+    // "relative" path escapes the repository entirely.
+    const realDir = realpathSync(dir);
+    const rel = relative(topLevel, join(realDir, basename(localStatePath)))
+        .split(sep)
+        .join("/");
+    const pattern = "/" + escapeGitignorePattern(rel);
+    try {
+        const excludePath = git(dir, ["rev-parse", "--path-format=absolute", "--git-path", "info/exclude"]);
+        if (!excludePath)
+            return { status: "failed", detail: "could not locate the git exclude file" };
+        mkdirSync(dirname(excludePath), { recursive: true });
+        const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf-8") : "";
+        if (existing.split(/\r?\n/).some((line) => line.trim() === pattern)) {
+            return { status: "already-ignored" };
+        }
+        const prefix = existing === "" || existing.endsWith("\n") ? "" : "\n";
+        writeFileSync(excludePath, existing +
+            prefix +
+            `\n# Added by 'primitive env use' — this machine's Primitive environment\n` +
+            `# selection is local state, not a team decision. Add the same pattern to a\n` +
+            `# committed .gitignore to make the coverage shared.\n` +
+            pattern +
+            "\n");
+        return { status: "excluded", excludePath, pattern };
+    }
+    catch (err) {
+        return { status: "failed", detail: err?.message || String(err) };
+    }
+}
+//# sourceMappingURL=local-state.js.map

package/dist/src/lib/local-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-state.js","sourceRoot":"","sources":["../../../src/lib/local-state.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/local-test-cases.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The case files on disk that the server has never been told about (#3061).
+ *
+ * A `<key>.tests/*.toml` sidecar is authored locally and becomes runnable only
+ * when `config push` registers it. The test verbs run the REGISTERED set, so a
+ * file nobody pushed contributes nothing to `Total Tests` — and until this
+ * module existed, nothing to the output either. `Total Tests: 3 / Failed: 0`
+ * beside four case files is a pass standing in for work that did not happen,
+ * and is indistinguishable from a case that genuinely ran.
+ *
+ * Naming those files is only useful if the naming is never wrong, so pairing
+ * here mirrors what push pairs with:
+ *   1. the sync manifest, which maps a file to the live case it manages even
+ *      when the file has since been renamed;
+ *   2. the file name pull would give the case — its committed key, or the slug
+ *      of an unkeyed case's name (web-admin, an older CLI or the raw API),
+ *      collision suffixes included — from the one shared naming rule in
+ *      `test-case-file-names.ts`.
+ * Both passes CLAIM: one live case accounts for one file, the way pull assigns
+ * one file per case and push's adoption pass pairs. Matching a name loosely
+ * instead would let a single registered "foo" excuse both `foo.toml` and a
+ * newly authored `foo-2.toml`, which is the silence this issue is about.
+ * Anything left over is a file no live case accounts for. The bias is toward
+ * silence: a pairing this module cannot make is a warning it does not print.
+ *
+ * Reads only — the scan never registers anything. `config push` stays the one
+ * verb that mutates the server, which is what the warning tells the user.
+ */
+/** What one suite's sidecar directory holds, against what is registered. */
+export interface LocalTestCaseScan {
+    /** Every `*.toml` case file in the directory, basename order. */
+    localFiles: string[];
+    /** The subset no registered case accounts for, basename order. */
+    unregistered: string[];
+}
+/** The `.primitive-sync.json` rows that map a sidecar to a live case. */
+export type ManagedTestCases = Record<string, {
+    id?: string;
+} | undefined>;
+/** Read the manifest's test-case rows, or nothing when it cannot be read. */
+export declare function readManagedTestCases(configDir: string): ManagedTestCases;
+/**
+ * The `*.toml` case files in a suite's sidecar directory, if it has one.
+ *
+ * An empty array means the directory is absent or holds no case file. A
+ * directory that cannot be READ throws instead of reporting nothing: this whole
+ * issue is about a silence indistinguishable from having no work, and callers
+ * turn the throw into a diagnostic that names the directory.
+ */
+export declare function listLocalTestCaseFiles(testsDir: string): string[];
+/**
+ * Which of a suite's local case files no registered case accounts for.
+ *
+ * `managedPrefix` is the manifest's namespace for this block —
+ * `<blockType>/<blockKey>` — so a row that maps `foo.toml` to a live case is
+ * read only for the block that owns it.
+ */
+export declare function scanLocalTestCases(params: {
+    testsDir: string;
+    registered: any[];
+    managed?: ManagedTestCases;
+    managedPrefix?: string;
+}): LocalTestCaseScan;