@sprigr/apps-app-sdk 0.8.4 → 0.8.6

package/README.md

@@ -73,7 +73,7 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.
 - `buildConfirmationPolicy({ irreversible, always, rules })` declares a dispatcher's policy beside its action registry; `checkConfirmationPolicy({ policy, registry, ungated, requiredInput })` returns every silent failure (dead rule, `(unset)` placeholder, money threshold, unclassified write) for a one-line test.
-- `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop. `pin` may hand `restore` a different type from the env (a per-actor token state), may throw (`connection_unavailable`) or return null to refuse (`connection_mismatch`); a restore that throws is `restore_failed` and the copy is kept.
+- `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop. `pin` may hand `restore` a different type from the env (a per-actor token state), may throw (`connection_unavailable`) or return null to refuse (`connection_mismatch`); a restore that throws is `restore_failed` and the copy is kept; a successful restore may return `newId`, `notRestored`, `extra` (spread into the payload) and `note` (appended after the fidelity sentence).
 - `safeCapture(scope, name, id, read)` and `offerUndo({ journal, entity, id, before, connection, fidelity, resource, describe, warning })`: the capture-then-offer halves for a write that is not behind an approval card (a dispatcher `update_*` action). `requireApproval` uses the same two on its granted pass.
 - `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`.
 

package/dist/index.d.ts

@@ -1153,9 +1153,11 @@ interface ApprovalGateOptions<E, P = E> {
     /**
      * Human label for a raw id, looked up THROUGH the pinned connection. Fall
      * back to the id on any miss; never guess, a confidently wrong card is worse
-     * than a terse one. Omit to always show the raw id.
+     * than a terse one. Omit to always show the raw id. `name` is the tool, or
+     * for a dispatcher the action, so a lookup can route by resource type when
+     * the id alone does not say what it is (an Asana gid).
      */
-    describeTarget?: (pinned: P, id: string) => Promise<string>;
+    describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
     /**
      * Where before-images go. Required when any spec declares `undo`. The
      * journal's own capture returns null rather than throwing, and this wrapper
@@ -1269,6 +1271,13 @@ interface RestoreResult {
     error?: string;
     notRestored?: string;
     extra?: Record<string, unknown>;
+    /**
+     * Free-form detail appended to the runner's note (the new gid, rows it
+     * could not refile, a sticker the vendor will not remove). The runner's own
+     * sentence on fidelity stays first so the model reads "replacement, not an
+     * undo" before the detail.
+     */
+    note?: string;
 }
 interface JournalRowLike<T = unknown> {
     entity: string;
@@ -1415,6 +1424,71 @@ interface OfferUndoArgs {
  */
 declare function offerUndo(args: OfferUndoArgs): Promise<AppUndoEnvelope | undefined>;
 
+/**
+ * Apply confirmation policies to a parsed `sprigr-app.json`, for an app's
+ * `gen:confirmation` script and its drift-guard test.
+ *
+ * Pure: takes the parsed manifest, mutates it in place, returns what it
+ * touched. The script owns the two lines of file I/O around it, so this
+ * module stays free of `node:fs` and safe to bundle into a Worker.
+ *
+ * Besides writing each policy, it retires the two mechanisms a policy
+ * supersedes: the legacy `confirmation_required` flag (a bare
+ * `{ always: true }` with no describe) and any app-declared `confirm` input
+ * (the platform injects its own top-level `confirm` wherever a policy is
+ * present). Both are stripped from EVERY tool, not only the gated ones,
+ * because a stray copy on an ungated tool is how a handler ends up reading
+ * a flag nothing enforces.
+ */
+
+interface ManifestDispatchBlock {
+    actionField: string;
+    actions: string[];
+    actionInputs?: Record<string, {
+        accepts: string[];
+        required?: string[];
+    }>;
+}
+interface ManifestToolLike {
+    name: string;
+    input_schema?: {
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [k: string]: unknown;
+    };
+    confirmation?: unknown;
+    confirmation_required?: boolean;
+    dispatch?: unknown;
+    [k: string]: unknown;
+}
+interface ManifestLike {
+    tools?: ManifestToolLike[];
+    [k: string]: unknown;
+}
+interface ApplyPoliciesOptions {
+    /** Tool name -> its policy: a tool-level rule, or `{ actions }` for a dispatcher. */
+    policies: Readonly<Record<string, ConfirmationPolicy>>;
+    /** Tool name -> dispatch block to write alongside (dispatchers only). */
+    dispatch?: Readonly<Record<string, ManifestDispatchBlock>>;
+    /** Delete `confirmation_required` from every tool. Default true. */
+    stripLegacyFlag?: boolean;
+    /** Delete an app-declared `confirm` input (property + required entry) from every tool. Default true. */
+    dropConfirmParam?: boolean;
+}
+/**
+ * Write the policies (and dispatch blocks) onto the named tools in place.
+ * Throws when a policy names a tool the manifest does not have, so a
+ * renamed tool cannot silently lose its gate. Returns the tool names touched.
+ */
+declare function applyConfirmationPolicies(manifest: ManifestLike, opts: ApplyPoliciesOptions): string[];
+/**
+ * True when applying the policies to a copy of the manifest changes nothing:
+ * the committed file is a fresh generation. The drift-guard test's one call.
+ */
+declare function manifestIsFresh(manifest: ManifestLike, opts: ApplyPoliciesOptions): boolean;
+/** The manifest, serialised the way the repo commits it (2-space, trailing newline). */
+declare function serializeManifest(manifest: ManifestLike): string;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -1815,4 +1889,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, set, tool, undoEnvelope, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, withSprigrEmitFallback };

package/dist/index.js

@@ -617,9 +617,9 @@ function rawIdOf(args, keys) {
 function isOk(result) {
   return !!result && typeof result === "object" && result.ok !== false;
 }
-async function safeLabel(fn, pinned, id) {
+async function safeLabel(fn, pinned, id, name) {
   try {
-    const label = await fn(pinned, id);
+    const label = await fn(pinned, id, name);
     return label && label.trim() ? label : id;
   } catch {
     return id;
@@ -629,11 +629,11 @@ async function pin(opts, env, connection) {
   if (!connection || !opts.pinEnv) return env;
   return opts.pinEnv(env, connection);
 }
-async function askPass(spec, params, env, opts, hashPrefix) {
+async function askPass(name, spec, params, env, opts, hashPrefix) {
   const connection = await opts.resolveConnection(env, params);
   const rawId = rawIdOf(params, spec.keys);
   const pinned = await pin(opts, env, connection);
-  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId) : rawId || "(unknown id)";
+  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
   const extra = spec.hash ? spec.hash(params) : [];
   return {
     ok: false,
@@ -688,7 +688,7 @@ function requireApproval(handlers, specs, opts) {
         const { [APPROVAL_GRANTED_KEY]: _granted, ...rest } = a;
         return grantedPass(name, spec, rest, env, opts, () => inner(rest, env, ctx));
       }
-      return askPass(spec, a, env, opts, []);
+      return askPass(name, spec, a, env, opts, []);
     };
   }
   return gated;
@@ -707,7 +707,7 @@ function dispatcherApproval(specs, opts) {
       if (a[APPROVAL_GRANTED_KEY] === true) {
         return grantedPass(action, spec, params, env, opts, write);
       }
-      return askPass(spec, params, env, opts, [action]);
+      return askPass(action, spec, params, env, opts, [action]);
     }
   };
 }
@@ -733,7 +733,7 @@ async function runUndoApply(args, opts) {
     };
   }
   const before = row.before;
-  if (!before || typeof before !== "object") {
+  if (!before || typeof before !== "object" || Array.isArray(before)) {
     return { ok: false, error: "before_image_unreadable", note: "The saved copy could not be read back. Nothing was changed." };
   }
   let pinned;
@@ -769,6 +769,7 @@ async function runUndoApply(args, opts) {
   await opts.journal.dropBefore(ref);
   const recreated = spec.fidelity === "recreated";
   const notRestored = result.notRestored ?? spec.notRestored;
+  const suffix = result.note && result.note.trim() ? ` ${result.note.trim()}` : "";
   return {
     ok: true,
     ...result.extra ?? {},
@@ -778,7 +779,7 @@ async function runUndoApply(args, opts) {
     new_id: result.newId ?? null,
     fidelity: spec.fidelity,
     ...notRestored ? { not_restored: notRestored } : {},
-    note: recreated ? `Created a NEW ${spec.resource}${result.newId ? ` (${result.newId})` : ""} from the saved copy. The original ${row.original_id} is still gone and its id will never be reissued.${notRestored ? ` Not restored: ${notRestored}.` : ""} Report this as a replacement, not as an undo.` : `Restored ${spec.resource} ${row.original_id} to its saved values.${notRestored ? ` Not restored: ${notRestored}.` : ""} Anything changed since the capture was overwritten.`
+    note: recreated ? `Created a NEW ${spec.resource}${result.newId ? ` (${result.newId})` : ""} from the saved copy. The original ${row.original_id} is still gone and its id will never be reissued.${notRestored ? ` Not restored: ${notRestored}.` : ""} Report this as a replacement, not as an undo.${suffix}` : `Restored ${spec.resource} ${row.original_id} to its saved values.${notRestored ? ` Not restored: ${notRestored}.` : ""} Anything changed since the capture was overwritten.${suffix}`
   };
 }
 
@@ -939,6 +940,48 @@ function checkConfirmationPolicy(input) {
   }
   return out.sort();
 }
+
+// src/write-protection/manifest.ts
+function applyConfirmationPolicies(manifest, opts) {
+  const tools = manifest.tools ?? [];
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  const touched = [];
+  for (const [name, policy] of Object.entries(opts.policies)) {
+    const tool2 = byName.get(name);
+    if (!tool2) throw new Error(`applyConfirmationPolicies: no tool named '${name}' in the manifest`);
+    tool2.confirmation = policy;
+    touched.push(name);
+  }
+  for (const [name, block] of Object.entries(opts.dispatch ?? {})) {
+    const tool2 = byName.get(name);
+    if (!tool2) throw new Error(`applyConfirmationPolicies: no tool named '${name}' in the manifest (dispatch)`);
+    tool2.dispatch = block;
+    if (!touched.includes(name)) touched.push(name);
+  }
+  const stripLegacy = opts.stripLegacyFlag ?? true;
+  const dropConfirm = opts.dropConfirmParam ?? true;
+  for (const tool2 of tools) {
+    if (stripLegacy) delete tool2.confirmation_required;
+    if (dropConfirm) {
+      const schema = tool2.input_schema;
+      if (schema?.properties && "confirm" in schema.properties) delete schema.properties.confirm;
+      if (schema?.required?.includes("confirm")) {
+        schema.required = schema.required.filter((k) => k !== "confirm");
+        if (schema.required.length === 0) delete schema.required;
+      }
+    }
+  }
+  return touched;
+}
+function manifestIsFresh(manifest, opts) {
+  const copy = JSON.parse(JSON.stringify(manifest));
+  applyConfirmationPolicies(copy, opts);
+  return JSON.stringify(copy) === JSON.stringify(manifest);
+}
+function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
 export {
   APPROVAL_GRANTED_KEY,
   DEFAULT_EMIT_TIMEOUT_MS,
@@ -951,6 +994,7 @@ export {
   actorKey,
   actorTool,
   appFileUrl,
+  applyConfirmationPolicies,
   approvalHash,
   archiveOfferRefusal,
   base64ToBytes,
@@ -978,6 +1022,7 @@ export {
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  manifestIsFresh,
   offerUndo,
   overlaySprigr,
   ownerFromActorKey,
@@ -995,6 +1040,7 @@ export {
   runUndoApply,
   safeCapture,
   seq,
+  serializeManifest,
   set,
   tool,
   undoEnvelope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",