@kici-dev/shared 0.1.0 → 0.1.2

package/dist/idempotency.d.ts

@@ -6,15 +6,17 @@
  * npm, git remotes, DNS, TF state, workflow step side effects) is wrapped
  * as an IdempotentStep whose check() returns a typed drift value or null.
  * Null means the system is already in the desired state — the runner
- * silently skips. A non-null drift means apply() would change state — the
- * runner asks the caller's confirm() before invoking apply(), unless yes
- * or dryRun overrides are set.
+ * silently skips, optionally invoking whenInSync() to surface the
+ * already-satisfied resource (e.g. an existing resource id). A non-null
+ * drift means apply() would change state — the runner asks the caller's
+ * confirm() before invoking apply(), unless yes or dryRun overrides are
+ * set. apply() returns the typed result of the change for the caller.
  *
  * The runner has no UI dependency. CLI consumers pass an inquirer-backed
  * confirm; future SDK / agent consumers pass their own policy function.
  * See `.claude/rules/idempotency.md` for the full rule and adopters.
  */
-export interface IdempotentStep<TDrift> {
+export interface IdempotentStep<TDrift, TInSync = void, TApplied = void> {
     /** Human-readable name; appears in logs and the confirm prompt. */
     name: string;
     /** Read-only inspection. Returns drift value if apply() would change
@@ -22,8 +24,15 @@ export interface IdempotentStep<TDrift> {
     check: () => Promise<TDrift | null>;
     /** Multi-line description of what apply() would do, given drift. */
     summarize: (drift: TDrift) => string;
-    /** Destructive action that brings the system into the desired state. */
-    apply: (drift: TDrift) => Promise<void>;
+    /** Destructive action that brings the system into the desired state.
+     *  Its return value is surfaced in StepResult.result on the 'applied'
+     *  outcome. */
+    apply: (drift: TDrift) => Promise<TApplied>;
+    /** Optional: runs when check() returns null. Use this to fetch the
+     *  already-satisfied resource (e.g. read the existing id when a
+     *  create-if-missing was already done). Return value is surfaced in
+     *  StepResult.result on the 'skipped' outcome. */
+    whenInSync?: () => Promise<TInSync>;
 }
 export type ConfirmFn = (message: string) => Promise<boolean>;
 export interface RunOptions {
@@ -38,9 +47,22 @@ export interface RunOptions {
     log?: (line: string) => void;
 }
 export type StepOutcome = 'skipped' | 'applied' | 'declined' | 'dry-run';
-export interface StepResult<TDrift> {
-    outcome: StepOutcome;
-    drift: TDrift | null;
-}
-export declare function runIdempotentStep<TDrift>(step: IdempotentStep<TDrift>, opts?: RunOptions): Promise<StepResult<TDrift>>;
+export type StepResult<TDrift, TInSync = void, TApplied = void> = {
+    outcome: 'skipped';
+    drift: null;
+    result: TInSync;
+} | {
+    outcome: 'applied';
+    drift: TDrift;
+    result: TApplied;
+} | {
+    outcome: 'declined';
+    drift: TDrift;
+    result: undefined;
+} | {
+    outcome: 'dry-run';
+    drift: TDrift;
+    result: undefined;
+};
+export declare function runIdempotentStep<TDrift, TInSync = void, TApplied = void>(step: IdempotentStep<TDrift, TInSync, TApplied>, opts?: RunOptions): Promise<StepResult<TDrift, TInSync, TApplied>>;
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.js

@@ -7,7 +7,8 @@ async function runIdempotentStep(step, opts = {}) {
 		log(`✓ ${step.name} — in sync, skipping`);
 		return {
 			outcome: "skipped",
-			drift: null
+			drift: null,
+			result: step.whenInSync ? await step.whenInSync() : void 0
 		};
 	}
 	log(`! ${step.name} — drift detected:`);
@@ -16,7 +17,8 @@ async function runIdempotentStep(step, opts = {}) {
 		log(`  (dry-run; would apply)`);
 		return {
 			outcome: "dry-run",
-			drift
+			drift,
+			result: void 0
 		};
 	}
 	let approved;
@@ -29,14 +31,16 @@ async function runIdempotentStep(step, opts = {}) {
 		log(`  declined; skipping`);
 		return {
 			outcome: "declined",
-			drift
+			drift,
+			result: void 0
 		};
 	}
-	await step.apply(drift);
+	const appliedResult = await step.apply(drift);
 	log(`✓ ${step.name} — applied`);
 	return {
 		outcome: "applied",
-		drift
+		drift,
+		result: appliedResult
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/shared",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
   "keywords": [
     "kici",
@@ -55,12 +55,6 @@
       "types": "./dist/idempotency-files.d.ts"
     }
   },
-  "scripts": {
-    "build": "node ../../scripts/build-ts.mjs && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npx tsx ../../hack/generate-sbom.ts --package packages/shared --name @kici-dev/shared"
-  },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1038.0",
     "@opentelemetry/api": "^1.9.1",
@@ -85,5 +79,10 @@
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.7.0",
     "@types/diff": "^7.0.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-ts.mjs && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/shared@0.1.0",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.0/d7d8e1f4-f421-4d0d-9f00-fe6277039666",
+  "name": "@kici-dev/shared@0.1.2",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.2/c6592910-3b7c-45da-bf64-9a87e8a37548",
   "creationInfo": {
-    "created": "2026-05-15T06:06:45Z",
+    "created": "2026-05-15T11:43:36Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -947,7 +947,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/shared",
-      "versionInfo": "0.1.0",
+      "versionInfo": "0.1.2",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -958,7 +958,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.2"
         }
       ],
       "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",