primitive-admin 1.0.61 → 1.0.62

package/dist/src/lib/sync-resource-types.d.ts

@@ -1,14 +1,14 @@
 /**
- * Shared layout metadata for the per-entity resource types `sync pull` writes
+ * Shared layout metadata for the per-entity resource types `config pull` writes
  * into a sync slot (issue #1659).
  *
- * `sync pull` writes one file per server entity and records what it wrote in
+ * `config pull` writes one file per server entity and records what it wrote in
  * `.primitive-sync.json` (`SyncState.entities[<slot>]`). Until #1659 it never
  * removed a local file whose entity had disappeared server-side, so the next
- * `sync push` — which treats local TOML as the source of truth — silently
+ * `config push` — which treats local TOML as the source of truth — silently
  * re-created the just-deleted entity.
  *
- * This module holds the narrow descriptor the prune pass and `sync diff` share:
+ * This module holds the narrow descriptor the prune pass and `config diff` share:
  * directory, extension, state slot, key→filename derivation, and the sidecar
  * test-directory block type. The pull write loops deliberately stay as they are
  * — this table is layout metadata, not a write framework.
@@ -16,6 +16,12 @@
 import type { SyncState } from "../types/index.js";
 import type { ApiClient } from "./api-client.js";
 export type SyncEntitySlot = keyof SyncState["entities"];
+/**
+ * A block whose test cases round-trip as a `<key>.tests/` sidecar. Integrations
+ * joined the other three in #2769 — their cases used to live server-side only,
+ * which made them the one configuration surface with no file to review.
+ */
+export type TestBlockType = "prompt" | "workflow" | "script" | "integration";
 export interface SyncResourceType {
     /** Singular name used in pull/diff output, e.g. `"rule-set"`. */
     label: string;
@@ -26,7 +32,7 @@ export interface SyncResourceType {
     /** Slot in `SyncState.entities` recording what a prior pull managed. */
     stateSlot: SyncEntitySlot;
     /**
-     * Entity key → the file basename `sync pull` writes for it. This must match
+     * Entity key → the file basename `config pull` writes for it. This must match
      * the write side exactly, so prune only ever targets a file pull created.
      */
     fileFromKey(key: string): string;
@@ -35,7 +41,15 @@ export interface SyncResourceType {
      * Pruning an entity also removes its test directory and the matching
      * `entities.testCases` records.
      */
-    testBlockType?: "prompt" | "workflow" | "script";
+    testBlockType?: TestBlockType;
+    /**
+     * Directory holding the entity's named configuration bodies, when the type
+     * has them (#2645: `workflows/<key>.configs/`). Pruning the entity removes it
+     * for the same reason it removes `<key>.tests/` — the configs belonged to a
+     * block that is gone, and a surviving directory would re-create them on the
+     * next push.
+     */
+    namedConfigsDirFromKey?(key: string): string;
     /**
      * Whether this type's server listing returns *every* key, so "absent from the
      * listing" really means "gone from the server".
@@ -43,7 +57,7 @@ export interface SyncResourceType {
      * Prune deletes files, so a successful fetch is not enough — the response also
      * has to be complete. Two shapes make a listing complete: the cursor-paginating
      * admin endpoints (integrations/webhooks/prompts/workflows — server returns
-     * `nextCursor` and `sync pull` drains it with `fetchAll`), and the config
+     * `nextCursor` and `config pull` drains it with `fetchAll`), and the config
      * listings that drain every DynamoDB page server-side via `queryAllPages`
      * (#1668). Before #1668 the config listings returned a single 100-row page with
      * a 200 and no cursor, so an app past the page boundary got a silently
@@ -60,7 +74,7 @@ export interface SyncResourceType {
      * version marker: the CLI npm publish is coupled to the production deploy (so
      * new-CLI-vs-old-server is a narrow window), the worst case is git-recoverable
      * local file deletion touching nothing server-side, and it only affects apps
-     * with >100 entities of one config type — whose `sync pull` was already
+     * with >100 entities of one config type — whose `config pull` was already
      * silently incomplete before this change.
      *
      * The flag remains as a guard: a future type whose listing is not yet complete
@@ -81,13 +95,13 @@ export declare function ruleSetFileKey(ruleSet: {
 /**
  * Every per-entity resource type in a sync slot. `app.toml` and `vars.toml` are
  * root singletons, not per-entity directories, so they are not listed here —
- * var removal is already handled within-file by `sync push` (`planVarsPush`).
+ * var removal is already handled within-file by `config push` (`planVarsPush`).
  */
 export declare const SYNC_RESOURCE_TYPES: SyncResourceType[];
 /**
  * Outcome of a server fetch that establishes which entities of a type exist.
  *
- * `sync pull` historically swallowed several list errors with `.catch(() => [])`,
+ * `config pull` historically swallowed several list errors with `.catch(() => [])`,
  * which makes a transient 401/500/network error indistinguishable from "the app
  * has none of these". Pruning off that empty list would delete every local file
  * of the type, so prune consumes this explicit outcome instead.
@@ -112,6 +126,24 @@ export declare function attemptFetch<T>(fn: () => Promise<T>): Promise<{
  * able to steer an `unlinkSync` outside the sync slot.
  */
 export declare function isSafeSyncFilename(filename: string): boolean;
+/**
+ * Whether a test-case attachment filename may be written to (or read from) the
+ * sidecar attachment directory (#2769).
+ *
+ * Attachment names come from the SERVER: pull writes each one into
+ * `<key>.tests/<slug>/`, so a stored name carrying a separator or a `..`
+ * segment would place a file outside the sync tree entirely. The rule is the
+ * same one state-derived filenames follow, plus a refusal of any leading-dot
+ * traversal spelling.
+ */
+export declare function isSafeAttachmentFilename(filename: string): boolean;
+/**
+ * The absolute path an attachment may be written to, or `null` when the name is
+ * unsafe or resolves outside `attachDir` (#2769). Both halves matter: the name
+ * check states the rule, and the resolved-path check enforces it against
+ * platform quirks the name check cannot anticipate.
+ */
+export declare function attachmentWritePath(attachDir: string, filename: string): string | null;
 export interface PrunePlan {
     /** Entity keys whose managed file should be removed. */
     keys: string[];
@@ -141,7 +173,7 @@ export interface PrunePlan {
  * `SyncState.entities[<slot>]`, so a previous pull wrote its file) and is
  * **absent from the server keys** this pull fetched. A local file that was
  * never in prior state was hand-authored — it is left alone and reported by
- * `sync diff` as new.
+ * `config diff` as new.
  *
  * Pure and side-effect-free (the caller owns the `unlinkSync`) so the safety
  * rules are unit-testable without a live server.
@@ -175,7 +207,7 @@ export declare function preserveUnwrittenEntries<T>(written: Record<string, T>,
  * a command.
  *
  * `includeUntracked` decides whether an untracked file counts as a change:
- * - `true` (default) suits "am I about to overwrite something?" — `sync revert`
+ * - `true` (default) suits "am I about to overwrite something?" — `config revert`
  *   would clobber an untracked file just the same.
  * - `false` suits "did the operator edit this file?" — an untracked file is the
  *   ordinary state of a pulled file in a sync dir that was never committed, and
@@ -196,10 +228,18 @@ export declare function hasUncommittedChanges(path: string, options?: {
  * way to be absent from the export is to have been deleted.
  */
 export declare const ABSENT_FROM_EXPORT = "absent from sync export (deleted on server)";
-/** `sync diff` status for a local file whose managed entity is gone. */
+/** `config diff` status for a local file whose managed entity is gone. */
 export declare const LOCAL_ONLY_ABSENT = "local only (absent from export)";
-/** `sync diff` status for a local file the operator authored themselves. */
+/** `config diff` status for a local file the operator authored themselves. */
 export declare const LOCAL_ONLY_NEW = "local only";
+/**
+ * `config diff` status for a local file `config push` would refuse (#2880).
+ *
+ * Its own status rather than a hint on a Synced row: the whole point is that
+ * the file is NOT pushable, and the counts a caller reads to decide "is there
+ * anything to do?" have to say so.
+ */
+export declare const VALIDATION_ERROR = "validation error";
 /**
  * Classify a local file that has no matching server entity (issue #1659).
  *
@@ -225,7 +265,7 @@ export interface PruneResult {
  *
  * A file with uncommitted git edits is kept and reported instead: the operator
  * may be mid-way through authoring a change they meant to push. Everything
- * removed here is recoverable from the pre-pull snapshot via `sync revert`.
+ * removed here is recoverable from the pre-pull snapshot via `config revert`.
  */
 export declare function applyPrune(options: {
     configDir: string;
@@ -246,7 +286,7 @@ export declare const addressById: PruneAddressOf;
 export declare const addressByKey: PruneAddressOf;
 /**
  * Live modified timestamp used by the drift check. Most admin/app detail
- * endpoints serialize `modifiedAt` at the top level (the same field `sync pull`
+ * endpoints serialize `modifiedAt` at the top level (the same field `config pull`
  * records into state), with `updatedAt` as a defensive fallback. Two detail
  * endpoints nest the entity under a wrapper key and need their own extractors
  * below (`workflowPruneModifiedAt`, `emailTemplatePruneModifiedAt`) so the
@@ -265,10 +305,26 @@ export declare const workflowPruneModifiedAt: (detail: any) => string | undefine
  * Email-template detail-read extractor. `getEmailTemplate` returns
  * `{ emailType, label, hasOverride, override, default, variables }`; the
  * editable copy `sync` manages — and its `modifiedAt` — live under `override`
- * (null when there is no override). `sync pull` likewise records
+ * (null when there is no override). `config pull` likewise records
  * `template.override?.modifiedAt`, so the drift check must read the same path.
  */
 export declare const emailTemplatePruneModifiedAt: (detail: any) => string | undefined;
+/**
+ * Split a metadata-category key into the `resourceType`/`category` pair it
+ * names, or `null` when it is not exactly two non-empty components joined by a
+ * single `#`.
+ *
+ * Load-bearing for prune (#2762). Prune point-reads a candidate BEFORE deciding
+ * what to do with it, and only a missing address short-circuits that fetch — so
+ * a corrupt state key that still produced an address would be read with
+ * `undefined` in the request path, and the resulting 404 would be classified
+ * "already gone", silently dropping the state entry. Failing here instead
+ * routes such a key to the `no-id` skip: no client call, state retained.
+ */
+export declare function parseMetadataCategoryKey(key: string): {
+    resourceType: string;
+    category: string;
+} | null;
 /**
  * How to confirm and delete one resource type during push-prune. Narrow by
  * design (state slot + address + detail-fetch + drift field + delete) rather
@@ -279,7 +335,7 @@ export interface PushPruneSpec {
     resourceType: SyncResourceType;
     /**
      * Derive the entity key a local managed file declares — the SAME derivation
-     * the type's `sync push` loop uses (`<in-file identity> || basename`). Prune
+     * the type's `config push` loop uses (`<in-file identity> || basename`). Prune
      * collects the set of these across every file in the type's directory and
      * treats a prior-state key as a candidate only when NO local file declares
      * it. This must mirror push exactly: a file renamed but keeping its internal
@@ -294,16 +350,23 @@ export interface PushPruneSpec {
     modifiedAtOf: (detail: any) => string | undefined;
     /**
      * Delete the confirmed entity; rejects with `ConflictError` (409) when the
-     * entity is still referenced. `null` for a type whose CLI delete surface has
-     * not landed yet (metadata-category-configs, gated on #1426): a candidate of
-     * such a type is reported "no delete surface yet" rather than deleted.
+     * entity is still referenced. `null` for a type with no delete surface, whose
+     * candidates are reported "no delete surface" rather than deleted — a
+     * fail-safe no shipped spec uses since #2762 wired the last one.
      */
     deleteEntity: ((client: ApiClient, appId: string, address: string) => Promise<void>) | null;
+    /**
+     * A consequence of deleting this type the prune plan must state before the
+     * operator confirms — printed under the item's "will delete" line, in
+     * `--dry-run` too. Only metadata-category-configs carry one: their stored
+     * values survive the definition and become unreachable (#2762).
+     */
+    deleteCaveat?: string;
 }
 /**
  * Every resource type push-prune can retire. Id-addressed types (integrations,
  * webhooks, cron-triggers, blob-buckets, prompts, workflows, transforms,
- * rule-sets) fetch/delete by the stored id; key-addressed types (database-types,
+ * rule-sets) fetch/delete by the stored id; key-addressed types (database-type-configs,
  * group-type-configs, collection-type-configs, email-templates) by the key.
  *
  * `--force` (the CLI's existing "override baseline drift" flag) only relaxes the
@@ -314,11 +377,11 @@ export interface PushPruneSpec {
 export declare const PUSH_PRUNE_SPECS: PushPruneSpec[];
 /**
  * The set of entity keys the local managed files of a type declare — collected
- * the way `sync push` derives keys: parse every file in the type's directory
+ * the way `config push` derives keys: parse every file in the type's directory
  * and read its declared identity (`<in-file key> || basename`), NOT by assuming
  * the file lives at its canonical `<key>.toml` path.
  *
- * This is the crux of the #1655 destructive-delete fix. `sync push` accepts a
+ * This is the crux of the #1655 destructive-delete fix. `config push` accepts a
  * managed file at a **noncanonical filename** (e.g. `prompts/custom.toml` with
  * `prompt.key = "greeting"`) and still updates the `greeting` entity. Collecting
  * declared keys — rather than checking whether `greeting.toml` exists — means a
@@ -337,11 +400,11 @@ export declare function collectLocalDeclaredKeys(input: {
  *
  * A key is a candidate iff it was in the prior state slot (a prior pull managed
  * it) AND **no** local file in the type's directory declares that key (via
- * {@link collectLocalDeclaredKeys}, mirroring how `sync push` derives keys). A
+ * {@link collectLocalDeclaredKeys}, mirroring how `config push` derives keys). A
  * key still declared by some file — even one renamed away from the canonical
- * `<key>.toml` path — is left alone, since `sync push` would update it, not
+ * `<key>.toml` path — is left alone, since `config push` would update it, not
  * delete it (issue #1655). A file whose key was never in prior state was
- * hand-authored and is left for `sync push` to create; it is never a candidate.
+ * hand-authored and is left for `config push` to create; it is never a candidate.
  */
 export declare function collectPushPruneCandidates(input: {
     spec: PushPruneSpec;
@@ -365,7 +428,10 @@ export interface PushPruneFetch {
 export type PushPruneSkipReason = 
 /** State entry has no usable id/key (corrupt or partial state). */
 "no-id"
-/** Type has no CLI delete surface yet (metadata-category-configs, #1426). */
+/**
+ * The spec carries no delete surface. A fail-safe: since #2762 every shipped
+ * spec can delete, so this arm only fires for a type wired without one.
+ */
  | "unsupported"
 /** Live `modifiedAt` differs from prior state — edited out-of-band. */
  | "drift"
@@ -404,6 +470,47 @@ export declare function decidePushPruneCandidate(input: {
     fetch: PushPruneFetch;
     force: boolean;
 }): PushPruneDecision;
+/**
+ * What a failed prune DELETE call means for the entity's sync-state slot.
+ *
+ * `raced-absent` — the entity was deleted out-of-band between the point read
+ * and this call. The desired state is met, so the delete counts as success and
+ * its stale slot goes; anything else keeps the slot so a re-run retries.
+ */
+export type PruneDeleteFailure = "raced-absent" | "blocked" | "failed";
+/**
+ * Classify an error thrown by a prune delete — one arm for every type.
+ *
+ * Keyed on the status alone (`ConflictError` is an `ApiError` with 409), so no
+ * per-type carve-out can creep into the push command's delete loop and make the
+ * race recovery true for some types and not others (#2762).
+ */
+export declare function classifyPruneDeleteFailure(err: unknown): PruneDeleteFailure;
+/** One line of the `config push --prune` plan, ready to color and print. */
+export interface PrunePlanLine {
+    kind: "delete" | "absent" | "skip";
+    /** The status prefix the CLI colors: "will delete", "skipped — …". */
+    status: string;
+    /** The uncolored remainder: `<type>: <key>`. */
+    detail: string;
+    /** An extra line printed under this one — the type's `deleteCaveat`. */
+    note?: string;
+}
+/**
+ * Render the prune plan the operator reads before the batch confirmation.
+ *
+ * Pure, and here rather than in `sync.ts`, so what the plan states about a type
+ * is testable without a server — specifically that a type's `deleteCaveat`
+ * (metadata's orphaned values, which used to live in the retired verb's confirm
+ * prompt) appears under its delete lines and nowhere else. `config push` renders
+ * the plan ONCE, before the `--dry-run` branch, so both paths print the same
+ * lines (#2762).
+ */
+export declare function formatPrunePlan(items: Array<{
+    spec: PushPruneSpec;
+    key: string;
+    decision: PushPruneDecision;
+}>): PrunePlanLine[];
 /**
  * Remove a pruned block's sidecar `<key>.tests/` directory and its
  * `entities.testCases` state records. The main file is already gone (that is
@@ -423,13 +530,13 @@ export declare function removePrunedSidecar(options: {
     removed: string[];
     removedTestCaseKeys: string[];
 };
-/** `sync diff` status for a managed remote entity whose local file is gone. */
+/** `config diff` status for a managed remote entity whose local file is gone. */
 export declare const REMOTE_ONLY_WILL_DELETE = "remote only (will delete with push --prune)";
-/** `sync diff` status for a server entity that was never synced (hand-created). */
+/** `config diff` status for a server entity that was never synced (hand-created). */
 export declare const REMOTE_ONLY_UNMANAGED = "remote only (left alone)";
 /**
  * Classify a "remote only" entity (present server-side, no local file) for
- * `sync diff` (issue #1655). A key the prior pull managed means the operator
+ * `config diff` (issue #1655). A key the prior pull managed means the operator
  * deleted its local file and `push --prune` will delete the remote entity; a key
  * never synced was authored on the server and is left alone. Prior sync state is
  * the discriminator, exactly as it is for the local-only / pull-prune split.