@toolproof-npm/shared 0.1.14

package/README.md

@@ -0,0 +1,55 @@
+# @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/constants.d.ts

@@ -0,0 +1,65 @@
+export declare const CONSTANTS: {
+    readonly SCHEMA: {
+        readonly FormatData: "FormatData";
+        readonly TypeData: "TypeData";
+        readonly SignatureData: "SignatureData";
+        readonly JobData: "JobData";
+        readonly Execution: "Execution";
+        readonly ResourceMap: "ResourceMap";
+    };
+    readonly STORAGE: {
+        readonly BUCKETS: {
+            readonly tp_shapes: "tp-shapes";
+            readonly tp_resources: "tp-resources";
+        };
+        readonly COLLECTIONS: {
+            readonly shapes: "shapes";
+            readonly resources: "resources";
+        };
+        readonly FILTER: {
+            readonly members: "members";
+            readonly specials: "specials";
+        };
+    };
+    readonly SHAPES: {
+        readonly formats: "formats";
+        readonly types: "types";
+    };
+    readonly SHAPES_PSEUDO: {
+        readonly roles: "roles";
+    };
+    readonly RESOURCES: {
+        readonly resources: "resources";
+        readonly jobs: "jobs";
+    };
+    readonly STEP: {
+        readonly work: "work";
+        readonly branch: "branch";
+        readonly while: "while";
+        readonly for: "for";
+    };
+    readonly WORKFLOW: {
+        readonly execution: "execution";
+        readonly workflow: "workflow";
+        readonly workflowSpec: "workflowSpec";
+    };
+    readonly ENGINE: {
+        readonly GraphRunWorkflow: "GraphRunWorkflow";
+    };
+    readonly SPECIALS: {
+        readonly FORMAT_ApplicationPrimitive: "FORMAT-ApplicationPrimitive";
+        readonly FORMAT_ApplicationJson: "FORMAT-ApplicationJson";
+        readonly FORMAT_ApplicationJob: "FORMAT-ApplicationJob";
+        readonly TYPE_Boolean: "TYPE-Boolean";
+        readonly TYPE_Integer: "TYPE-Integer";
+        readonly TYPE_Job: "TYPE-Job";
+        readonly TYPE_WorkflowSpec: "TYPE-WorkflowSpec";
+        readonly ROLE_BUILDER: "ROLE-Builder";
+        readonly JOB_Engine: "JOB-Engine";
+        readonly BOOLEAN_false: "RESOURCE-CSTseYlo7VxcNFl9RMvD";
+        readonly BOOLEAN_true: "RESOURCE-V4TFSye2F7bBnEsSrpH4";
+    };
+    readonly TESTING: {
+        readonly Integer_Zero: "TYPE-Integer/3335e31095a13a9a2b0ea41ca7d92a458780cd5671dc0a440a72cc1b1c4f2c81";
+    };
+};

package/dist/constants.js

@@ -0,0 +1,65 @@
+export const CONSTANTS = {
+    SCHEMA: {
+        FormatData: 'FormatData',
+        TypeData: 'TypeData',
+        SignatureData: 'SignatureData',
+        JobData: 'JobData',
+        Execution: 'Execution',
+        ResourceMap: 'ResourceMap',
+    },
+    STORAGE: {
+        BUCKETS: {
+            tp_shapes: 'tp-shapes',
+            tp_resources: 'tp-resources',
+        },
+        COLLECTIONS: {
+            shapes: 'shapes',
+            resources: 'resources',
+        },
+        FILTER: {
+            members: 'members',
+            specials: 'specials',
+        }
+    },
+    SHAPES: {
+        formats: 'formats',
+        types: 'types',
+    },
+    SHAPES_PSEUDO: {
+        roles: 'roles',
+    },
+    RESOURCES: {
+        resources: 'resources',
+        jobs: 'jobs',
+    },
+    STEP: {
+        work: 'work',
+        branch: 'branch',
+        while: 'while',
+        for: 'for',
+    },
+    WORKFLOW: {
+        execution: 'execution',
+        workflow: 'workflow',
+        workflowSpec: 'workflowSpec',
+    },
+    ENGINE: {
+        GraphRunWorkflow: 'GraphRunWorkflow',
+    },
+    SPECIALS: {
+        FORMAT_ApplicationPrimitive: 'FORMAT-ApplicationPrimitive',
+        FORMAT_ApplicationJson: 'FORMAT-ApplicationJson',
+        FORMAT_ApplicationJob: 'FORMAT-ApplicationJob',
+        TYPE_Boolean: 'TYPE-Boolean',
+        TYPE_Integer: 'TYPE-Integer',
+        TYPE_Job: 'TYPE-Job',
+        TYPE_WorkflowSpec: 'TYPE-WorkflowSpec',
+        ROLE_BUILDER: 'ROLE-Builder',
+        JOB_Engine: 'JOB-Engine',
+        BOOLEAN_false: 'RESOURCE-CSTseYlo7VxcNFl9RMvD',
+        BOOLEAN_true: 'RESOURCE-V4TFSye2F7bBnEsSrpH4',
+    },
+    TESTING: {
+        Integer_Zero: 'TYPE-Integer/3335e31095a13a9a2b0ea41ca7d92a458780cd5671dc0a440a72cc1b1c4f2c81',
+    }
+};

package/dist/firestoreAdminHelpers.d.ts

@@ -0,0 +1,7 @@
+import type { TypeIdJson } from '@toolproof-npm/schema';
+import type { FilterConst, ShapeConst, RoleConst, StepConst, WorkflowConst, ShapeMeta, ShapeData, ShapeMetaMap, ShapeDataMap, ResourceMetaMap, ResourceDataMap, ResourceConst } from './types.d.ts';
+export declare function getNewId(identifiable: ShapeConst | RoleConst | ResourceConst | StepConst | WorkflowConst): string;
+export declare function listShapesMeta<T extends ShapeMeta>(groupKey: ShapeConst, filterConfig: Record<FilterConst, boolean>): Promise<ShapeMetaMap<T>>;
+export declare function listResourcesMeta(typeIds: TypeIdJson[]): Promise<ResourceMetaMap>;
+export declare function listShapesData<T extends ShapeData>(groupKey: ShapeConst, filterConfig: Record<FilterConst, boolean>): Promise<ShapeDataMap<T>>;
+export declare function listResourcesData(typeIds: TypeIdJson[]): Promise<ResourceDataMap>;

package/dist/firestoreAdminHelpers.js

@@ -0,0 +1,192 @@
+import { CONSTANTS } from './constants.js';
+import { dbAdmin, storageAdmin } from "./firestoreAdminInit.js";
+export function getNewId(identifiable) {
+    const base = identifiable.toUpperCase();
+    const normalized = base.endsWith('S') ? base.slice(0, -1) : base;
+    const prefix = normalized + '-';
+    const docRef = dbAdmin.collection(CONSTANTS.STORAGE.COLLECTIONS.shapes).doc(identifiable).collection(CONSTANTS.STORAGE.FILTER.members).doc();
+    return prefix + docRef.id;
+}
+export async function listShapesMeta(groupKey, filterConfig) {
+    const baseRef = dbAdmin
+        .collection(CONSTANTS.STORAGE.COLLECTIONS.shapes)
+        .doc(groupKey);
+    const entries = await Promise.all([
+        filterConfig.members
+            ? baseRef.collection(CONSTANTS.STORAGE.FILTER.members).get().then(snap => snap.docs.map(d => {
+                const data = d.data();
+                return { ...data, id: d.id };
+            }))
+            : Promise.resolve([]),
+        filterConfig.specials
+            ? baseRef.collection(CONSTANTS.STORAGE.FILTER.specials).get().then(snap => snap.docs.map(d => {
+                const data = d.data();
+                return { ...data, id: d.id };
+            }))
+            : Promise.resolve([]),
+    ]);
+    const [members, specials] = entries;
+    return { members, specials };
+}
+export async function listResourcesMeta(typeIds) {
+    const collectionName = CONSTANTS.STORAGE.COLLECTIONS.resources;
+    const entries = await Promise.all(typeIds.map(async (typeId) => {
+        const snap = await dbAdmin
+            .collection(collectionName)
+            .doc(typeId)
+            .collection(CONSTANTS.STORAGE.FILTER.members)
+            .get();
+        const items = snap.docs.map(d => {
+            const data = d.data();
+            // Ensure id field is present (doc id is the resourceId)
+            return { ...data, id: d.id };
+        });
+        return [typeId, items];
+    }));
+    return Object.fromEntries(entries);
+}
+export async function listShapesData(groupKey, filterConfig) {
+    const bucket = storageAdmin.bucket(CONSTANTS.STORAGE.BUCKETS.tp_shapes);
+    const prefix = `${groupKey}/`;
+    const [files] = await bucket.getFiles({ prefix });
+    const result = {
+        members: [],
+        specials: [],
+    };
+    const tasks = files
+        .filter(f => !(f.name.endsWith('/') || f.name.split('/').pop() === ''))
+        .map(async (file) => {
+        const meta = file.metadata || (await file.getMetadata())[0];
+        const subNameRaw = meta?.metadata?.filter;
+        const subName = (subNameRaw === CONSTANTS.STORAGE.FILTER.specials
+            ? CONSTANTS.STORAGE.FILTER.specials
+            : CONSTANTS.STORAGE.FILTER.members);
+        if (!filterConfig[subName])
+            return;
+        const [buf] = await file.download();
+        const json = JSON.parse(buf.toString('utf8'));
+        result[subName].push(json);
+    });
+    await Promise.all(tasks);
+    return result;
+}
+export async function listResourcesData(typeIds) {
+    const bucket = storageAdmin.bucket(CONSTANTS.STORAGE.BUCKETS.tp_resources);
+    async function fetchFilesUnder(typeId) {
+        const prefix = `${typeId}/`;
+        const [found] = await bucket.getFiles({ prefix });
+        const files = found.filter(f => {
+            const name = f.name || '';
+            if (!name || name.endsWith('/'))
+                return false;
+            return true;
+        });
+        if (!files.length)
+            return [];
+        const items = await Promise.all(files.map(async (file) => {
+            try {
+                const [buf] = await file.download();
+                const meta = file.metadata || (await file.getMetadata())[0];
+                const data = JSON.parse(buf.toString('utf8'));
+                return { data, meta, name: file.name };
+            }
+            catch {
+                return null;
+            }
+        }));
+        return items.filter(Boolean);
+    }
+    const entries = await Promise.all(typeIds.map(async (typeId) => {
+        const rows = await fetchFilesUnder(typeId);
+        const items = rows.map(({ data, meta, name }) => {
+            const flat = meta?.metadata ?? {};
+            // Reconstruct nested object from flattened keys (dot and array index notation)
+            const root = {};
+            for (const [k, vRaw] of Object.entries(flat)) {
+                if (typeof vRaw !== 'string')
+                    continue; // GCS should store only strings
+                const vStr = vRaw.trim();
+                // Attempt JSON parse for non-simple primitives
+                let value = vStr;
+                if ((vStr.startsWith('{') && vStr.endsWith('}')) || (vStr.startsWith('[') && vStr.endsWith(']'))) {
+                    try {
+                        value = JSON.parse(vStr);
+                    }
+                    catch {
+                        value = vStr;
+                    }
+                }
+                // Split by '.' while preserving array indices
+                const segments = k.split('.');
+                let cursor = root;
+                for (let i = 0; i < segments.length; i++) {
+                    const seg = segments[i];
+                    const arrIdxMatch = seg.match(/^(.*)\[(\d+)\]$/);
+                    if (arrIdxMatch) {
+                        const base = arrIdxMatch[1];
+                        const idx = parseInt(arrIdxMatch[2], 10);
+                        if (!cursor[base])
+                            cursor[base] = [];
+                        if (!Array.isArray(cursor[base]))
+                            cursor[base] = [];
+                        while (cursor[base].length <= idx)
+                            cursor[base].push(undefined);
+                        if (i === segments.length - 1) {
+                            cursor[base][idx] = value;
+                        }
+                        else {
+                            if (!cursor[base][idx])
+                                cursor[base][idx] = {};
+                            cursor = cursor[base][idx];
+                        }
+                    }
+                    else {
+                        if (i === segments.length - 1) {
+                            cursor[seg] = value;
+                        }
+                        else {
+                            if (!cursor[seg] || typeof cursor[seg] !== 'object')
+                                cursor[seg] = {};
+                            cursor = cursor[seg];
+                        }
+                    }
+                }
+            }
+            const idMeta = root.id;
+            const typeIdMeta = root.typeId;
+            // creationContext may be flattened as creationContext.roleId or direct roleId
+            const roleId = (root.creationContext?.roleId ?? root.roleId);
+            const executionId = (root.creationContext?.executionId ?? root.executionId);
+            const kind = root.kind;
+            const path = root.path;
+            const timestamp = root.timestamp;
+            const missing = [
+                ['id', idMeta],
+                ['typeId', typeIdMeta],
+                ['roleId', roleId],
+                ['executionId', executionId],
+                ['kind', kind],
+                ['path', path],
+                ['timestamp', timestamp],
+            ].filter(([_, v]) => typeof v !== 'string' || v.length === 0);
+            if (missing.length) {
+                const keys = missing.map(([k]) => k).join(', ');
+                throw new Error(`Missing required metadata keys [${keys}] for resource file: ${name}`);
+            }
+            return {
+                id: idMeta,
+                typeId: typeIdMeta,
+                creationContext: {
+                    roleId: roleId,
+                    executionId: executionId,
+                },
+                kind: kind,
+                path: path,
+                timestamp: timestamp,
+                extractedData: data,
+            };
+        });
+        return [typeId, items];
+    }));
+    return Object.fromEntries(entries);
+}

package/dist/firestoreAdminInit.d.ts

@@ -0,0 +1,3 @@
+declare const dbAdmin: FirebaseFirestore.Firestore;
+declare const storageAdmin: import("firebase-admin/storage").Storage;
+export { dbAdmin, storageAdmin };

package/dist/firestoreAdminInit.js

@@ -0,0 +1,36 @@
+import { getApp, getApps, initializeApp, applicationDefault, cert } from 'firebase-admin/app';
+import { getFirestore } from 'firebase-admin/firestore';
+import { getStorage } from 'firebase-admin/storage';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+// Resolve credentials: prefer GOOGLE_APPLICATION_CREDENTIALS, fallback to local gcp-key.json, else ADC
+function resolveCredential() {
+    const jsonString = process.env.GOOGLE_APPLICATION_CREDENTIALS_JSON;
+    const envPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+    const localKeyPath = path.join(process.cwd(), 'gcp-key.json');
+    try {
+        if (jsonString) {
+            const json = JSON.parse(jsonString);
+            return cert(json);
+        }
+        if (envPath && existsSync(envPath)) {
+            const json = JSON.parse(readFileSync(envPath, 'utf8'));
+            return cert(json);
+        }
+        if (existsSync(localKeyPath)) {
+            const json = JSON.parse(readFileSync(localKeyPath, 'utf8'));
+            return cert(json);
+        }
+    }
+    catch {
+        // fall through to ADC
+    }
+    return applicationDefault();
+}
+const app = getApps().length ? getApp() : initializeApp({
+    credential: resolveCredential(),
+    projectId: "toolproof-563fe",
+});
+const dbAdmin = getFirestore(app);
+const storageAdmin = getStorage(app);
+export { dbAdmin, storageAdmin };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * as CONSTANTS from './constants.js';
+export * as TYPES from './types.js';
+export * from './firestoreAdminHelpers.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * as CONSTANTS from './constants.js';
+export * as TYPES from './types.js';
+export * from './firestoreAdminHelpers.js';

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { ResourceIdJson, ExecutionIdJson, RoleIdJson, RoleLiteralJson, TypeIdJson, FormatMetaJson, FormatDataJson, TypeMetaJson, TypeDataJson, ResourceMetaJson, ResourceDataJson } from '@toolproof-npm/schema';
+import { CONSTANTS } from './constants.js';
+export type BucketConst = typeof CONSTANTS.STORAGE.BUCKETS.tp_shapes | typeof CONSTANTS.STORAGE.BUCKETS.tp_resources;
+export type CollectionConst = typeof CONSTANTS.STORAGE.COLLECTIONS.shapes | typeof CONSTANTS.STORAGE.COLLECTIONS.resources;
+export type FilterConst = typeof CONSTANTS.STORAGE.FILTER.members | typeof CONSTANTS.STORAGE.FILTER.specials;
+export type ShapeConst = typeof CONSTANTS.SHAPES.formats | typeof CONSTANTS.SHAPES.types;
+export type RoleConst = typeof CONSTANTS.SHAPES_PSEUDO.roles;
+export type ResourceConst = typeof CONSTANTS.RESOURCES.resources;
+export type StepConst = typeof CONSTANTS.STEP.work | typeof CONSTANTS.STEP.branch | typeof CONSTANTS.STEP.while | typeof CONSTANTS.STEP.for;
+export type WorkflowConst = typeof CONSTANTS.WORKFLOW.workflow | typeof CONSTANTS.WORKFLOW.workflowSpec | typeof CONSTANTS.WORKFLOW.execution;
+export interface DryRunManagerType {
+    dryRunMode: boolean;
+    delay: number;
+    drySocketMode: boolean;
+}
+export type Role = {
+    id: RoleIdJson;
+} & RoleLiteralJson;
+export type ShapeData = FormatDataJson | TypeDataJson;
+export type ShapeMeta = FormatMetaJson | TypeMetaJson;
+export type ShapeDataMap<T extends ShapeData> = Record<FilterConst, T[]>;
+export type ShapeMetaMap<T extends ShapeMeta> = Record<FilterConst, T[]>;
+export type ResourceMetaMap = Record<TypeIdJson, ResourceMetaJson[]>;
+export type ResourceDataMap = Record<TypeIdJson, ResourceDataJson[]>;
+export type ExternallyProvidedResourceMeta = {
+    id: ResourceIdJson;
+    typeId: TypeIdJson;
+    creationContext: {
+        roleId: RoleIdJson;
+        executionId: ExecutionIdJson;
+    };
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@toolproof-npm/shared",
+    "version": "0.1.14",
+    "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/_lib"
+    },
+    "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"
+        },
+        "./constants": {
+            "import": "./dist/constants.js",
+            "types": "./dist/constants.d.ts"
+        },
+        "./types": {
+            "import": "./dist/types.js",
+            "types": "./dist/types.d.ts"
+        },
+        "./server": {
+            "node": "./dist/firestoreAdminHelpers.js",
+            "types": "./dist/firestoreAdminHelpers.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc -b"
+    },
+    "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.12",
+        "firebase-admin": "^13.6.0"
+    }
+}