@toolproof-npm/shared 0.1.99 → 0.1.101

package/README.md

@@ -1,56 +1,56 @@
-# @toolproof-npm/shared
-
-Core library utilities for ToolProof.
-
-## Installation
-
-```bash
-pnpm add @toolproof-npm/shared
-# or
-npm install @toolproof-npm/shared
-# or
-yarn add @toolproof-npm/shared
-```
-
-## Usage
-
-### Basic Import
-
-```typescript
-import { /* your exports */ } from '@toolproof-npm/shared';
-```
-
-### Constants
-
-```typescript
-import { /* constants */ } from '@toolproof-npm/shared/constants';
-```
-
-### Types
-
-```typescript
-import { /* types */ } from '@toolproof-npm/shared/types';
-```
-
-### Server Utilities (Node.js only)
-
-```typescript
-import { /* server utilities */ } from '@toolproof-npm/shared/server';
-```
-
-## Features
-
-- TypeScript support with full type definitions
-- ESM module format
-- Tree-shakeable exports
-- Server-side utilities for Firestore admin operations
-
-## Requirements
-
-- Node.js 16+ 
-- TypeScript 4.5+ (for TypeScript projects)
-
-## License
-
-MIT
-
+# @toolproof-npm/shared
+
+Core library utilities for ToolProof.
+
+## Installation
+
+```bash
+pnpm add @toolproof-npm/shared
+# or
+npm install @toolproof-npm/shared
+# or
+yarn add @toolproof-npm/shared
+```
+
+## Usage
+
+### Basic Import
+
+```typescript
+import { /* your exports */ } from '@toolproof-npm/shared';
+```
+
+### Constants
+
+```typescript
+import { /* constants */ } from '@toolproof-npm/shared/constants';
+```
+
+### Types
+
+```typescript
+import { /* types */ } from '@toolproof-npm/shared/types';
+```
+
+### Server Utilities (Node.js only)
+
+```typescript
+import { /* server utilities */ } from '@toolproof-npm/shared/server';
+```
+
+## Features
+
+- TypeScript support with full type definitions
+- ESM module format
+- Tree-shakeable exports
+- Server-side utilities for Firestore admin operations
+
+## Requirements
+
+- Node.js 16+ 
+- TypeScript 4.5+ (for TypeScript projects)
+
+## License
+
+MIT
+

package/dist/_lib/utils/makeHelpers.d.ts

@@ -0,0 +1,3 @@
+import type { WorkStepJson, WhileStepJson, ForStepJson, JobJson } from '@toolproof-npm/schema';
+export declare const makeWorkStepFromJob: (job: JobJson) => Promise<WorkStepJson>;
+export declare const makeLoopStepFromJob: (job: JobJson, whenJob: JobJson, kind: "for" | "while") => Promise<ForStepJson | WhileStepJson>;

package/dist/_lib/utils/makeHelpers.js

@@ -0,0 +1,58 @@
+import { CONSTANTS } from '@toolproof-npm/shared/constants';
+import { getNewIdentity } from '@toolproof-npm/shared/server';
+// DOC: Helper function to construct an Execution object from a job
+const makeExecutionFromJob = async (job, executionRef) => {
+    const execIdentity = executionRef ?? await getNewIdentity(CONSTANTS.TERMINALS.execution);
+    const inputBindingMap = {};
+    const inputs = job.roles.inputMap;
+    await Promise.all(Object.keys(inputs).map(async (resourceRoleRef) => {
+        const resourceId = await getNewIdentity(CONSTANTS.TERMINALS.resource);
+        inputBindingMap[resourceRoleRef] = resourceId;
+    }));
+    const outputBindingMap = {};
+    const outputs = job.roles.outputMap;
+    await Promise.all(Object.keys(outputs).map(async (resourceRoleRef) => {
+        const resourceId = await getNewIdentity(CONSTANTS.TERMINALS.resource);
+        outputBindingMap[resourceRoleRef] = resourceId;
+    }));
+    return {
+        identity: execIdentity,
+        jobRef: job.identity,
+        roleBindings: {
+            inputBindingMap,
+            outputBindingMap
+        }
+    };
+};
+// DOC: Helper function to construct a WorkStep object from an jobMetaJson (does not append to statelessStrategy.steps)
+export const makeWorkStepFromJob = async (job) => {
+    const workStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
+    const executionRef = workStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase()); // ATTENTION: use function
+    const execution = await makeExecutionFromJob(job, executionRef);
+    const newWorkStep = {
+        identity: workStepIdentity,
+        kind: CONSTANTS.STEPS.work,
+        execution
+    };
+    return newWorkStep;
+};
+// DOC: Helper function to construct a ForStep or WhileStep from a job
+export const makeLoopStepFromJob = async (job, whenJob, kind) => {
+    // Create the "what" WorkStep from the provided job
+    const whatWorkStep = await makeWorkStepFromJob(job);
+    // Create the "when" WorkStep from the LessThan job
+    const whenWorkStep = await makeWorkStepFromJob(whenJob);
+    // Generate loop step identity based on kind
+    const stepIdentity = (kind === 'for'
+        ? await getNewIdentity(CONSTANTS.STEPS.for)
+        : await getNewIdentity(CONSTANTS.STEPS.while));
+    // Assemble the loop step
+    return {
+        identity: stepIdentity,
+        kind,
+        case: {
+            what: whatWorkStep,
+            when: whenWorkStep
+        }
+    };
+};

package/dist/_lib/utils/resourceChain.d.ts

@@ -0,0 +1,21 @@
+import type { CreationContextJson, ResourceJson, ResourceMissingJson, ResourcePotentialOutputJson, StrategyStateJson } from '@toolproof-npm/schema';
+export type ResolveResult = {
+    status: 'materialized';
+    entry: ResourceJson;
+    path: CreationContextJson[];
+} | {
+    status: 'missing';
+    entry: ResourceMissingJson;
+    path: CreationContextJson[];
+} | {
+    status: 'potential-output';
+    entry: ResourcePotentialOutputJson;
+    path: CreationContextJson[];
+} | {
+    status: 'unresolved';
+    reason: 'not-found' | 'cycle' | 'depth-exceeded';
+    path: CreationContextJson[];
+};
+export declare function resolveResourceChain(strategyState: StrategyStateJson, start: CreationContextJson, opts?: {
+    maxDepth?: number;
+}): ResolveResult;

package/dist/_lib/utils/resourceChain.js

@@ -0,0 +1,40 @@
+export function resolveResourceChain(strategyState, start, opts) {
+    const maxDepth = opts?.maxDepth ?? 50;
+    const visited = new Set();
+    const path = [];
+    let current = start;
+    for (let depth = 0; depth <= maxDepth; depth++) {
+        path.push(current);
+        const visitKey = `${current.executionRef}::${current.resourceRoleRef}`;
+        if (visited.has(visitKey)) {
+            return { status: 'unresolved', reason: 'cycle', path };
+        }
+        visited.add(visitKey);
+        const bucket = strategyState[current.executionRef];
+        if (!bucket)
+            return { status: 'unresolved', reason: 'not-found', path };
+        const entry = bucket[current.resourceRoleRef];
+        if (!entry)
+            return { status: 'unresolved', reason: 'not-found', path };
+        if (entry.kind === 'materialized') {
+            return { status: 'materialized', entry: entry, path };
+        }
+        if (entry.kind === 'missing') {
+            return { status: 'missing', entry: entry, path };
+        }
+        if (entry.kind === 'potential-output') {
+            return { status: 'potential-output', entry: entry, path };
+        }
+        // potential-input: follow ref backwards
+        if (entry.kind === 'potential-input') {
+            const rpi = entry.creationContext;
+            if (!rpi)
+                return { status: 'unresolved', reason: 'not-found', path };
+            current = rpi;
+            continue;
+        }
+        // Unknown case
+        return { status: 'unresolved', reason: 'not-found', path };
+    }
+    return { status: 'unresolved', reason: 'depth-exceeded', path };
+}

package/dist/_lib/utils/roleResourceBinding.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutionIdentityJson, ResourceJson, ResourceRoleIdentityJson, StatefulStrategyJson } from '@toolproof-npm/schema';
+export declare function bindInputRes(statefulStrategy: StatefulStrategyJson, executionRef: ExecutionIdentityJson, resourceRoleIdentity: ResourceRoleIdentityJson, resource: ResourceJson): StatefulStrategyJson;
+export declare function bindInputRef(statefulStrategy: StatefulStrategyJson, targetExecRef: ExecutionIdentityJson, resourceRoleIdentity: ResourceRoleIdentityJson, source: {
+    executionRef: ExecutionIdentityJson;
+    resourceRoleRef: ResourceRoleIdentityJson;
+}): StatefulStrategyJson;
+export declare function clearInputBinding(statefulStrategy: StatefulStrategyJson, execRef: ExecutionIdentityJson, resourceRoleRef: ResourceRoleIdentityJson): StatefulStrategyJson;

package/dist/_lib/utils/roleResourceBinding.js

@@ -0,0 +1,87 @@
+import { resolveResourceChain } from './resourceChain.js';
+export function bindInputRes(statefulStrategy, executionRef, resourceRoleIdentity, resource) {
+    const strategyState = statefulStrategy.strategyState;
+    const bucket = strategyState[executionRef] ?? {};
+    return {
+        ...statefulStrategy,
+        strategyState: {
+            ...strategyState,
+            [executionRef]: {
+                ...bucket,
+                [resourceRoleIdentity]: resource,
+            },
+        },
+    };
+}
+export function bindInputRef(statefulStrategy, targetExecRef, resourceRoleIdentity, source) {
+    const strategyState = statefulStrategy.strategyState;
+    const sourceEntry = strategyState?.[source.executionRef]?.[source.resourceRoleRef];
+    if (!sourceEntry)
+        throw new Error(`resourceEntry not found for source (${source.executionRef}, ${source.resourceRoleRef})`);
+    const bucket = strategyState[targetExecRef] ?? {};
+    const result = resolveResourceChain(strategyState, { executionRef: source.executionRef, resourceRoleRef: source.resourceRoleRef });
+    if (result.status === 'materialized') {
+        return {
+            ...statefulStrategy,
+            strategyState: {
+                ...strategyState,
+                [targetExecRef]: {
+                    ...bucket,
+                    [resourceRoleIdentity]: result.entry,
+                },
+            },
+        };
+    }
+    if (result.status === 'missing') {
+        const missing = result.entry;
+        const reusedMissing = {
+            identity: missing.identity,
+            resourceTypeRef: missing.resourceTypeRef,
+            kind: 'missing',
+        };
+        return {
+            ...statefulStrategy,
+            strategyState: {
+                ...strategyState,
+                [targetExecRef]: {
+                    ...bucket,
+                    [resourceRoleIdentity]: reusedMissing,
+                },
+            },
+        };
+    }
+    if (result.status === 'potential-output') {
+        const potentialInput = {
+            identity: sourceEntry.identity,
+            resourceTypeRef: sourceEntry.resourceTypeRef,
+            creationContext: { executionRef: source.executionRef, resourceRoleRef: source.resourceRoleRef },
+            kind: 'potential-input',
+        };
+        return {
+            ...statefulStrategy,
+            strategyState: {
+                ...strategyState,
+                [targetExecRef]: {
+                    ...bucket,
+                    [resourceRoleIdentity]: potentialInput,
+                },
+            },
+        };
+    }
+    throw new Error(`Failed to resolve resource chain: ${result.reason}`);
+}
+export function clearInputBinding(statefulStrategy, execRef, resourceRoleRef) {
+    const strategyState = statefulStrategy.strategyState;
+    const bucket = strategyState?.[execRef];
+    if (!bucket?.[resourceRoleRef])
+        return statefulStrategy;
+    const nextBucket = { ...bucket };
+    delete nextBucket[resourceRoleRef];
+    return {
+        ...statefulStrategy,
+        strategyState: {
+            ...strategyState,
+            [execRef]: nextBucket,
+        },
+    };
+}

package/dist/_lib/utils/stepCreation.d.ts

@@ -5,3 +5,4 @@ export declare const createBranchStepFromJobPairs: (cases: {
     whatJob: JobJson;
     whenJob: JobJson;
 }[]) => Promise<BranchStepJson>;
+export declare const cloneForStep: (forStep: ForStepJson) => Promise<ForStepJson>;

package/dist/_lib/utils/stepCreation.js

@@ -76,3 +76,51 @@ export const createBranchStepFromJobPairs = async (cases) => {
         cases: casesWithWorkSteps
     };
 };
+// DOC: Helper function to clone a ForStep with new identities for steps and executions, preserving job references and bindings
+export const cloneForStep = async (forStep) => {
+    // Generate new ForStep identity
+    const newForStepIdentity = await getNewIdentity(CONSTANTS.STEPS.for);
+    // Clone the "what" WorkStep
+    const originalWhatWorkStep = forStep.case.what;
+    const newWhatWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
+    const newWhatExecutionIdentity = newWhatWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhatExecution = {
+        identity: newWhatExecutionIdentity,
+        jobRef: originalWhatWorkStep.execution.jobRef,
+        roleBindings: {
+            inputBindingMap: { ...originalWhatWorkStep.execution.roleBindings.inputBindingMap },
+            outputBindingMap: { ...originalWhatWorkStep.execution.roleBindings.outputBindingMap }
+        }
+    };
+    const newWhatWorkStep = {
+        identity: newWhatWorkStepIdentity,
+        kind: CONSTANTS.STEPS.work,
+        execution: newWhatExecution
+    };
+    // Clone the "when" WorkStep
+    const originalWhenWorkStep = forStep.case.when;
+    const newWhenWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
+    const newWhenExecutionIdentity = newWhenWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhenExecution = {
+        identity: newWhenExecutionIdentity,
+        jobRef: originalWhenWorkStep.execution.jobRef,
+        roleBindings: {
+            inputBindingMap: { ...originalWhenWorkStep.execution.roleBindings.inputBindingMap },
+            outputBindingMap: { ...originalWhenWorkStep.execution.roleBindings.outputBindingMap }
+        }
+    };
+    const newWhenWorkStep = {
+        identity: newWhenWorkStepIdentity,
+        kind: CONSTANTS.STEPS.work,
+        execution: newWhenExecution
+    };
+    // Assemble the cloned ForStep
+    return {
+        identity: newForStepIdentity,
+        kind: CONSTANTS.STEPS.for,
+        case: {
+            what: newWhatWorkStep,
+            when: newWhenWorkStep
+        }
+    };
+};

package/dist/_lib/utils/utils.d.ts

@@ -1,24 +1,4 @@
-import type { ResourceIdentityJson, ResourceTypeIdentityJson, ResourceJson, ResourceMissingJson, JobJson, ResourcePotentialOutputJson, StrategyStateJson, CreationContextJson } from '@toolproof-npm/schema';
+import type { ResourceIdentityJson, ResourceTypeIdentityJson, ResourceJson, JobJson } from '@toolproof-npm/schema';
 import type { ResourceMap } from '../types.js';
 export declare function extractResourcesByType(resourceMap: ResourceMap, resourceTypeRef: ResourceTypeIdentityJson): Record<ResourceIdentityJson, ResourceJson>;
 export declare function extractJobMap(resourceMap: ResourceMap): Map<`JOB-${string}`, JobJson>;
-export type ResolveResult = {
-    status: 'materialized';
-    entry: ResourceJson;
-    path: CreationContextJson[];
-} | {
-    status: 'missing';
-    entry: ResourceMissingJson;
-    path: CreationContextJson[];
-} | {
-    status: 'potential-output';
-    entry: ResourcePotentialOutputJson;
-    path: CreationContextJson[];
-} | {
-    status: 'unresolved';
-    reason: 'not-found' | 'cycle' | 'depth-exceeded';
-    path: CreationContextJson[];
-};
-export declare function resolveResourceChain(strategyState: StrategyStateJson, start: CreationContextJson, opts?: {
-    maxDepth?: number;
-}): ResolveResult;

package/dist/_lib/utils/utils.js

@@ -16,43 +16,3 @@ export function extractJobMap(resourceMap) {
     });
     return jobMap;
 }
-export function resolveResourceChain(strategyState, start, opts) {
-    const maxDepth = opts?.maxDepth ?? 50;
-    const visited = new Set();
-    const path = [];
-    let current = start;
-    for (let depth = 0; depth <= maxDepth; depth++) {
-        path.push(current);
-        const visitKey = `${current.executionRef}::${current.resourceRoleRef}`;
-        if (visited.has(visitKey)) {
-            return { status: 'unresolved', reason: 'cycle', path };
-        }
-        visited.add(visitKey);
-        const bucket = strategyState[current.executionRef];
-        if (!bucket)
-            return { status: 'unresolved', reason: 'not-found', path };
-        const entry = bucket[current.resourceRoleRef];
-        if (!entry)
-            return { status: 'unresolved', reason: 'not-found', path };
-        if (entry.kind === 'materialized') {
-            return { status: 'materialized', entry: entry, path };
-        }
-        if (entry.kind === 'missing') {
-            return { status: 'missing', entry: entry, path };
-        }
-        if (entry.kind === 'potential-output') {
-            return { status: 'potential-output', entry: entry, path };
-        }
-        // potential-input: follow ref backwards
-        if (entry.kind === 'potential-input') {
-            const rpi = entry.creationContext;
-            if (!rpi)
-                return { status: 'unresolved', reason: 'not-found', path };
-            current = rpi;
-            continue;
-        }
-        // Unknown case
-        return { status: 'unresolved', reason: 'not-found', path };
-    }
-    return { status: 'unresolved', reason: 'depth-exceeded', path };
-}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export * as TYPES from './_lib/types.js';
 export * as UTILS from './_lib/utils/utils.js';
 export * as RESOURCE_CREATION from './_lib/utils/resourceCreation.js';
 export * as STEP_CREATION from './_lib/utils/stepCreation.js';
+export * as ROLE_RESOURCE_BINDINGS from './_lib/utils/roleResourceBinding.js';
 export * from './firebaseAdminHelpers.js';
 export * from './firebaseAdminInit.js';

package/dist/index.js

@@ -3,5 +3,6 @@ export * as TYPES from './_lib/types.js';
 export * as UTILS from './_lib/utils/utils.js';
 export * as RESOURCE_CREATION from './_lib/utils/resourceCreation.js';
 export * as STEP_CREATION from './_lib/utils/stepCreation.js';
+export * as ROLE_RESOURCE_BINDINGS from './_lib/utils/roleResourceBinding.js';
 export * from './firebaseAdminHelpers.js';
 export * from './firebaseAdminInit.js';

package/package.json

@@ -1,65 +1,65 @@
 {
-    "name": "@toolproof-npm/shared",
-    "version": "0.1.99",
-    "description": "Core library utilities for ToolProof",
-    "keywords": [
-        "toolproof",
-        "utilities",
-        "library"
-    ],
-    "author": "ToolProof Team",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/ToolProof/core.git",
-        "directory": "packages/shared"
+  "name": "@toolproof-npm/shared",
+  "version": "0.1.101",
+  "description": "Core library utilities for ToolProof",
+  "keywords": [
+    "toolproof",
+    "utilities",
+    "library"
+  ],
+  "author": "ToolProof Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ToolProof/core.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/ToolProof/core#readme",
+  "bugs": {
+    "url": "https://github.com/ToolProof/core/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
-    "homepage": "https://github.com/ToolProof/core#readme",
-    "bugs": {
-        "url": "https://github.com/ToolProof/core/issues"
+    "./constants": {
+      "import": "./dist/constants.js",
+      "types": "./dist/constants.d.ts"
     },
-    "type": "module",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "sideEffects": false,
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        },
-        "./constants": {
-            "import": "./dist/constants.js",
-            "types": "./dist/constants.d.ts"
-        },
-        "./types": {
-            "import": "./dist/_lib/types.js",
-            "types": "./dist/_lib/types.d.ts"
-        },
-        "./utils": {
-            "import": "./dist/_lib/utils/utils.js",
-            "types": "./dist/_lib/utils/utils.d.ts"
-        },
-        "./server": {
-            "node": "./dist/firebaseAdminHelpers.js",
-            "types": "./dist/firebaseAdminHelpers.d.ts"
-        }
+    "./types": {
+      "import": "./dist/_lib/types.js",
+      "types": "./dist/_lib/types.d.ts"
     },
-    "scripts": {
-        "build": "tsc -b"
+    "./utils": {
+      "import": "./dist/_lib/utils/utils.js",
+      "types": "./dist/_lib/utils/utils.d.ts"
     },
-    "files": [
-        "dist",
-        "README.md"
-    ],
-    "devDependencies": {
-        "@google-cloud/storage": "^7.17.3",
-        "@types/node": "^20.19.25",
-        "json-schema-to-typescript": "^15.0.4",
-        "ts-node": "^10.9.2",
-        "typescript": "^5.9.3"
-    },
-    "dependencies": {
-        "@toolproof-npm/schema": "^0.1.68",
-        "firebase-admin": "^13.6.0"
+    "./server": {
+      "node": "./dist/firebaseAdminHelpers.js",
+      "types": "./dist/firebaseAdminHelpers.d.ts"
     }
-}
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@google-cloud/storage": "^7.17.3",
+    "@types/node": "^20.19.25",
+    "json-schema-to-typescript": "^15.0.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@toolproof-npm/schema": "^0.1.68",
+    "firebase-admin": "^13.6.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}