engrrajonahmed/obrimbasecli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

upd: helper utility updated

Browse Source
This commit is contained in:
Rajon Ahmed 2026-06-20 12:08:18 +08:00
parent 022e672b88
commit 35ac79c175
Signed by: engrrajonahmed
GPG Key ID: 19C3D328D8C8F65F
15 changed files with 867 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
data/framework/glossary/handler.go
View File

@ -1,3 +1,51 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Handler
|
| Purpose:
| - Provide a JSON resource provider for the Retriever utility.
| - Embed, parse, and expose a complete JSON resource payload.
| - Abstract resource storage details from consumers.
|
| Guideline:
| - Register the handler through retriever.ObrimRetrieverJsonRegister().
| - Associate the handler with a unique resource identifier.
| - Return the complete parsed resource payload only.
| - Delegate retrieval, traversal, filtering, and selection logic to Retriever.
| - Do not implement business logic within the handler.
| - Do not perform querying, transformation, or resource discovery.
|
| Example:
| - retriever.ObrimRetrieverJsonRegister(
| "software/metadata",
| obrimHandlerProvider{},
| )
| - response := retriever.ObrimRetriever(
| "json",
| map[string]any{
| "resource": "software/metadata",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package handler package handler
import ( import (

48
data/framework/metadata/handler.go
View File

@ -1,3 +1,51 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Handler
|
| Purpose:
| - Provide a JSON resource provider for the Retriever utility.
| - Embed, parse, and expose a complete JSON resource payload.
| - Abstract resource storage details from consumers.
|
| Guideline:
| - Register the handler through retriever.ObrimRetrieverJsonRegister().
| - Associate the handler with a unique resource identifier.
| - Return the complete parsed resource payload only.
| - Delegate retrieval, traversal, filtering, and selection logic to Retriever.
| - Do not implement business logic within the handler.
| - Do not perform querying, transformation, or resource discovery.
|
| Example:
| - retriever.ObrimRetrieverJsonRegister(
| "software/metadata",
| obrimHandlerProvider{},
| )
| - response := retriever.ObrimRetriever(
| "json",
| map[string]any{
| "resource": "software/metadata",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package handler package handler
import ( import (

48
data/software/glossary/handler.go
View File

@ -1,3 +1,51 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Handler
|
| Purpose:
| - Provide a JSON resource provider for the Retriever utility.
| - Embed, parse, and expose a complete JSON resource payload.
| - Abstract resource storage details from consumers.
|
| Guideline:
| - Register the handler through retriever.ObrimRetrieverJsonRegister().
| - Associate the handler with a unique resource identifier.
| - Return the complete parsed resource payload only.
| - Delegate retrieval, traversal, filtering, and selection logic to Retriever.
| - Do not implement business logic within the handler.
| - Do not perform querying, transformation, or resource discovery.
|
| Example:
| - retriever.ObrimRetrieverJsonRegister(
| "software/metadata",
| obrimHandlerProvider{},
| )
| - response := retriever.ObrimRetriever(
| "json",
| map[string]any{
| "resource": "software/metadata",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package handler package handler
import ( import (

48
data/software/metadata/handler.go
View File

@ -1,3 +1,51 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Handler
|
| Purpose:
| - Provide a JSON resource provider for the Retriever utility.
| - Embed, parse, and expose a complete JSON resource payload.
| - Abstract resource storage details from consumers.
|
| Guideline:
| - Register the handler through retriever.ObrimRetrieverJsonRegister().
| - Associate the handler with a unique resource identifier.
| - Return the complete parsed resource payload only.
| - Delegate retrieval, traversal, filtering, and selection logic to Retriever.
| - Do not implement business logic within the handler.
| - Do not perform querying, transformation, or resource discovery.
|
| Example:
| - retriever.ObrimRetrieverJsonRegister(
| "software/metadata",
| obrimHandlerProvider{},
| )
| - response := retriever.ObrimRetriever(
| "json",
| map[string]any{
| "resource": "software/metadata",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package handler package handler
import ( import (

79
essential/visible/service/helper/cipher/cipher.go
View File

@ -1,3 +1,82 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Cipher
|
| Purpose:
| - Provide reusable AES-256 encryption and decryption capabilities
| for file-based data processing.
|
| Guideline:
| - Use encrypt-standard for AES-256 encryption without salt metadata.
| - Use encrypt-salted for AES-256 encryption with embedded salt,
| signature, and version metadata.
| - Use decrypt-standard only for files produced by
| encrypt-standard.
| - Use decrypt-salted only for files produced by
| encrypt-salted.
| - Always provide a valid AES-256 compatible key.
| - Always provide valid input and output file paths.
| - Do not manually modify salted file headers, version
| information, or embedded salt metadata.
| - Treat generated salt as non-secret metadata required for
| successful decryption.
|
| Example:
| - ObrimCipher(
| "encrypt-standard",
| map[string]any{
| "key": "<32-byte-key>",
| "input": "./plain.txt",
| "output": "./encrypted.bin",
| },
| )
|
| - ObrimCipher(
| "encrypt-salted",
| map[string]any{
| "key": "<32-byte-key>",
| "input": "./plain.txt",
| "output": "./encrypted.obc",
| },
| )
|
| - ObrimCipher(
| "decrypt-standard",
| map[string]any{
| "key": "<32-byte-key>",
| "input": "./encrypted.bin",
| "output": "./plain.txt",
| },
| )
|
| - ObrimCipher(
| "decrypt-salted",
| map[string]any{
| "key": "<32-byte-key>",
| "input": "./encrypted.obc",
| "output": "./plain.txt",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package cipher package cipher
import ( import (

59
essential/visible/service/helper/codec/codec.go
View File

@ -1,3 +1,62 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Codec
|
| Purpose:
| - Provide reusable encoding and decoding capabilities for framework
| and software services.
|
| Guideline:
| - Use ObrimCodec() as the public entry point for all codec operations.
| - Always provide a valid operation type and configuration map.
| - Use supported formats only: base8, base10, base16, base32,
| base64, and sqids.
| - Validate all inputs before processing encoding or decoding requests.
| - Use charset and salt values consistently between encode and decode
| operations.
| - Use case configuration for non-sqids formats.
| - Use length configuration for sqids format.
| - Treat empty sqids inputs and outputs as operation failures.
| - Consume responses through the standardized status, code, and
| payload structure.
|
| Example:
| - ObrimCodec("encode", config)
| - ObrimCodec("decode", config)
| - ObrimCodec("encode", map[string]any{
| "format": "base64",
| "data": "example",
| "charset": "",
| "salt": "",
| "case": "lower",
| })
| - ObrimCodec("decode", map[string]any{
| "format": "sqids",
| "data": "abc123",
| "charset": "abcdefghijklmnopqrstuvwxyz",
| "salt": "",
| "length": 8,
| })
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package codec package codec
import ( import (

54
essential/visible/service/helper/datetime/datetime.go
View File

@ -1,3 +1,57 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Datetime Utility
|
| Purpose:
| - Retrieve the current date and time from either the host system
| clock or a trusted framework-managed NTP source and return the
| result using a framework-supported date/time format pattern.
|
| Guideline:
| - Use ObrimDatetime() as the primary entry point.
| - Always provide a valid datetime type.
| - Supported types are "local" and "trusted".
| - Always provide the "format" configuration key.
| - Use only framework-supported format patterns.
| - Expect all successful results to be returned as strings.
| - Use "local" when host system time is sufficient.
| - Use "trusted" when synchronized network time is required.
| - Handle both success and failure response codes.
|
| Example:
| - ObrimDatetime(
| "local",
| map[string]any{
| "format": "yyyy-MM-dd",
| },
| )
|
| - ObrimDatetime(
| "trusted",
| map[string]any{
| "format": "yyyy-MM-dd HH:mm:ss z",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package datetime package datetime
import ( import (

56
essential/visible/service/helper/filesystem/filesystem.go
View File

@ -1,3 +1,59 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Filesystem
|
| Purpose:
| - Provide reusable, deterministic, and OS-agnostic filesystem
| operations for files and directories through a unified execution
| interface.
|
| Guideline:
| - Use ObrimFilesystem() as the single public entry point.
| - Execute only one filesystem operation per invocation.
| - Validate operation type and configuration before execution.
| - Resolve filesystem paths through supported strategies.
| - Return structured and deterministic results for all executions.
| - Remain independent of runtime, CLI, and third-party frameworks.
| - Use Go standard library filesystem capabilities whenever possible.
|
| Example:
| - ObrimFilesystem("list", map[string]any{
| "strategy": "user",
| "recursive": true,
| })
|
| - ObrimFilesystem("check", map[string]any{
| "strategy": "custom",
| "base": "/tmp",
| "name": "example.txt",
| })
|
| - ObrimFilesystem("create", map[string]any{
| "entity": "directory",
| "strategy": "custom",
| "base": "/tmp",
| "name": "workspace",
| })
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package filesystem package filesystem
import ( import (

83
essential/visible/service/helper/hash/hash.go
View File

@ -1,3 +1,86 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Hash
|
| Purpose:
| - Generate and verify cryptographic hash values using standard
| or salted hashing methods for integrity verification,
| canonical fingerprinting, resource identification,
| comparison workflows, and security-oriented hashing
| requirements.
|
| Guideline:
| - Call ObrimHash() as the single public entry point.
| - Provide exactly two primary parameters: type and config.
| - Use type "calculate" to generate hash values.
| - Use type "compare" to verify hash values.
| - Use mode "standard" for deterministic hashing.
| - Use mode "salted" for salt-assisted hashing.
| - Use only supported algorithms for the selected mode.
| - Preserve generated salt values when future verification
| is required.
| - Always evaluate the returned status and code values before
| consuming payload data.
|
| Example:
| - ObrimHash(
| "calculate",
| map[string]any{
| "mode": "standard",
| "algorithm": "sha256",
| "value": "example",
| },
| )
|
| - ObrimHash(
| "calculate",
| map[string]any{
| "mode": "salted",
| "algorithm": "salted_sha512",
| "value": "example",
| },
| )
|
| - ObrimHash(
| "compare",
| map[string]any{
| "mode": "standard",
| "algorithm": "sha256",
| "value": "example",
| "hash": "<hash>",
| },
| )
|
| - ObrimHash(
| "compare",
| map[string]any{
| "mode": "salted",
| "algorithm": "salted_sha512",
| "value": "example",
| "hash": "<hash>",
| "salt": "<salt>",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package hash package hash
import ( import (

54
essential/visible/service/helper/key/key.go
View File

@ -1,3 +1,57 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Key
|
| Purpose:
| - Generate cryptographic key material through a type-driven
| orchestration workflow with strict validation, schema isolation,
| and algorithm-specific generation routines.
|
| Guideline:
| - Call ObrimKey() as the single public entry point.
| - Provide an explicit generation type and configuration.
| - Use "symmetric" type for AES key generation.
| - Use "asymmetric" type for ECC EdDSA key pair generation.
| - Provide only supported configuration fields.
| - Complete configuration validation before generation.
| - Consume generated key material only from successful responses.
| - Check response status and code before accessing payload data.
|
| Example:
| - ObrimKey(
| "symmetric",
| map[string]any{
| "algorithm": "aes",
| "key_size": 256,
| },
| )
|
| - ObrimKey(
| "asymmetric",
| map[string]any{
| "algorithm": "ecc",
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package key package key
import ( import (

40
essential/visible/service/helper/log/log.go
View File

@ -1,3 +1,43 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Log
|
| Purpose:
| - Provide framework-level structured logging capabilities.
| - Persist plaintext log entries using a deterministic and platform-aware storage strategy.
| - Enable reusable logging functionality for framework and software components.
|
| Guideline:
| - Use ObrimLog() to write structured log entries.
| - Use labels in the format SERVICENAME/UTILITYNAME or SERVICENAME/FEATURENAME.
| - Use human-readable messages suitable for operational diagnostics and tracing.
| - Allow the utility to manage log file creation and storage path resolution.
| - Use append-only logging to preserve historical log records.
|
| Example:
| - ObrimLog("SYSTEM/LOG", "Log utility initialized.")
| - ObrimLog("PROJECT/CREATE", "Project created successfully.")
| - ObrimLog("USER/AUTHENTICATION", "User authentication completed.")
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package log package log
import ( import (

58
essential/visible/service/helper/marker/marker.go
View File

@ -1,3 +1,61 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Marker
|
| Purpose:
| - Provide a unified utility for generating unique markers through
| time-based, random, and encoded generation strategies using a
| single standardized entry point.
|
| Guideline:
| - Use ObrimMarker() as the primary entry point for all marker
| generation operations.
| - Provide a supported marker type and the required configuration
| values for the selected generation strategy.
| - Consume responses through the standardized status, code, and
| payload structure.
| - Validate response status before accessing payload data.
| - Use time markers for distributed uniqueness requirements.
| - Use random markers for collision-resistant identifier generation.
| - Use encoded markers for deterministic identifier generation from
| source data.
|
| Example:
| - ObrimMarker("time", map[string]any{
| "epoch": 1704067200000,
| "instance": "NODE01",
| })
|
| - ObrimMarker("random", map[string]any{
| "length": 32,
| "charset": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
| })
|
| - ObrimMarker("encoded", map[string]any{
| "data": "customer-1001",
| "length": 24,
| "salt": "obrim",
| })
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package marker package marker
import ( import (

68
essential/visible/service/helper/progress/progress.go
View File

@ -1,3 +1,71 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Progress
|
| Purpose:
| - Manage, monitor, and report task progress through standardized
| lifecycle-aware progress tracking.
|
| Guideline:
| - Use "countable" type when progress can be measured using current
| and target numeric values.
| - Use "uncountable" type when progress is activity-based and cannot
| be represented by a completion percentage.
| - Always provide a valid lifecycle state before executing the utility.
| - Provide "current" and "target" values for countable progress
| tracking operations.
| - Provide a non-empty "placeholder" value for uncountable progress
| tracking operations.
| - Use returned payload data for CLI rendering, status reporting,
| and workflow monitoring.
| - Check the returned status and code before consuming payload data.
|
| Example:
| - ObrimProgress(
| "countable",
| map[string]any{
| "state": "running",
| "current": 45,
| "target": 100,
| },
| )
|
| - ObrimProgress(
| "uncountable",
| map[string]any{
| "state": "running",
| "placeholder": "Processing records...",
| },
| )
|
| - result := ObrimProgress(
| "countable",
| map[string]any{
| "state": "completed",
| "current": 100,
| "target": 100,
| },
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package progress package progress
import ( import (

81
essential/visible/service/helper/retriever/retriever.go
View File

@ -1,3 +1,84 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Retriever
|
| Purpose:
| - Retrieve data from supported resource providers through a unified
| retrieval interface while abstracting provider-specific
| implementation details from consumers.
|
| Guideline:
|
| ObrimRetriever()
| - Use for unified resource retrieval operations.
| - Select a supported retrieval type before execution.
| - Provide configuration according to the selected retrieval type.
| - Use resource retrieval for complete resource payloads.
| - Use path retrieval for individual nested values.
| - Use field retrieval for multiple selected values.
| - Do not provide both path and fields in the same request.
|
| ObrimRetrieverJsonRegister()
| - Register JSON providers before retrieval operations.
| - Use unique resource identifiers for provider registration.
| - Register one provider per resource identifier.
|
| ObrimRetrieverDbRegister()
| - Register database providers using unique resource identifiers.
| - Reserve registration for future database retrieval support.
| - Maintain resource-to-provider mappings through registration.
|
| Example:
|
| ObrimRetriever()
| - ObrimRetriever("json", map[string]any{
| "resource": "metadata",
| })
|
| - ObrimRetriever("json", map[string]any{
| "resource": "metadata",
| "path": "software.name",
| })
|
| - ObrimRetriever("json", map[string]any{
| "resource": "metadata",
| "fields": []string{
| "software.name",
| "software.version",
| },
| })
|
| ObrimRetrieverJsonRegister()
| - ObrimRetrieverJsonRegister(
| "metadata",
| metadataProvider,
| )
|
| ObrimRetrieverDbRegister()
| - ObrimRetrieverDbRegister(
| "database",
| databaseProvider,
| )
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package retriever package retriever
import ( import (

43
essential/visible/service/helper/status/status.go
View File

@ -1,3 +1,46 @@
/*
|--------------------------------------------------------------------------
| Metadata
|--------------------------------------------------------------------------
|
| Name:
| - Status
|
| Purpose:
| - Provide a framework-level CLI status utility that standardizes
| terminal message presentation using semantic labels and visual
| indicators to ensure consistent output across all softwares.
|
| Guideline:
| - Call ObrimStatus() whenever a standardized terminal status message
| must be emitted.
| - Use only supported semantic labels: INFO, WARNING, SUCCESS, ERROR.
| - Invalid, unsupported, or empty labels are automatically normalized
| to INFO.
| - Status operates through terminal output side-effects and does not
| return any value.
|
| Example:
| - ObrimStatus("INFO", "Application started.")
| - ObrimStatus("SUCCESS", "Configuration loaded.")
| - ObrimStatus("WARNING", "Configuration file not found.")
| - ObrimStatus("ERROR", "Unable to establish connection.")
|
|--------------------------------------------------------------------------
*/
/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
| - Rajon Ahmed
| - Scionite
|
|--------------------------------------------------------------------------
*/
package status package status
import ( import (