@deeep-network/riptide 0.1.1

package/README.md

@@ -0,0 +1,57 @@
+# @deeep-network/riptide
+
+Self-contained container orchestration library with lifecycle hooks for Coral Reef services.
+
+## Installation
+
+```bash
+npm install @deeep-network/riptide
+```
+
+## Quick Start
+
+### Create a New Service
+
+```bash
+npx @deeep-network/riptide init my-service
+```
+
+### With Options
+
+```bash
+# Create with API key validation
+npx @deeep-network/riptide init my-api --template with-secrets
+
+# Create with subprocess management
+npx @deeep-network/riptide init my-worker --template with-process
+
+# Create with Prometheus metrics
+npx @deeep-network/riptide init my-monitored --template with-metrics
+```
+
+## Templates
+
+- **basic** - Simple healthy service with minimal hooks
+- **with-secrets** - Includes API key validation and error handling
+- **with-process** - Manages subprocess lifecycle
+- **with-metrics** - Includes Prometheus metrics endpoint
+
+## CLI Commands
+
+```bash
+# Initialize a new service
+npx @deeep-network/riptide init <name> [options]
+
+# Start a service
+npx @deeep-network/riptide start
+
+# Validate hooks
+npx @deeep-network/riptide validate
+
+# Check health
+npx @deeep-network/riptide health
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+"use strict";var N=Object.create;var x=Object.defineProperty;var _=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var F=Object.getPrototypeOf,L=Object.prototype.hasOwnProperty;var n=(o,e)=>x(o,"name",{value:e,configurable:!0});var J=(o,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of A(e))!L.call(o,i)&&i!==t&&x(o,i,{get:()=>e[i],enumerable:!(r=_(e,i))||r.enumerable});return o};var u=(o,e,t)=>(t=o!=null?N(F(o)):{},J(e||!o||!o.__esModule?x(t,"default",{value:o,enumerable:!0}):t,o));var M=u(require("pino"));function y(o){return o instanceof Error&&"exitCode"in o&&typeof o.exitCode=="number"}n(y,"isRiptideError");var w=u(require("pino"));function P(o){let{level:e="info",format:t="pretty",serviceName:r}=o,i={level:e,timestamp:w.default.stdTimeFunctions.isoTime,formatters:{log:n(s=>({service:r,...s}),"log"),bindings:n(s=>{let{pid:a,hostname:c,...p}=s;return p},"bindings")}};return t==="pretty"&&!process.env.NODE_ENV?.includes("prod")?(0,w.default)({...i,transport:{target:"pino-pretty",options:{colorize:!0,translateTime:"SYS:standard",ignore:"pid,hostname"}}}):(0,w.default)(i)}n(P,"createLogger");var H=require("child_process"),d=require("fs"),U=u(require("http")),V=u(require("https")),C=u(require("path")),O=require("util");var q=(0,O.promisify)(H.exec);function R(){return{sleep:n(o=>new Promise(e=>setTimeout(e,o)),"sleep"),retry:n(async(o,e={})=>{let{maxAttempts:t=3,delay:r=1e3,backoffMultiplier:i=2,maxDelay:s=3e4}=e,a,c=r;for(let p=1;p<=t;p++)try{return await o()}catch(l){if(a=l instanceof Error?l:new Error(String(l)),p===t)throw a;await new Promise(m=>setTimeout(m,Math.min(c,s))),c*=i}throw a},"retry"),execCommand:n(async(o,e={})=>{let{timeout:t=3e4,cwd:r=process.cwd(),env:i=process.env}=e;try{let{stdout:s,stderr:a}=await q(o,{timeout:t,cwd:r,env:{...process.env,...i}});return{stdout:s.trim(),stderr:a.trim(),exitCode:0}}catch(s){if(s.killed&&s.signal==="SIGTERM"){let c=`Command timed out after ${t/1e3}s. Consider increasing timeout if command needs more time to complete: utils.execCommand('${o}', { timeout: ${t*2} })`,p=s.stderr?.trim()||"",l=p?`${p}
+
+${c}`:c,m=[];s.stdout?.trim()&&m.push(`STDOUT: ${s.stdout.trim()}`),l&&m.push(`STDERR: ${l}`);let j=[`Command execution timed out: ${o}`,...m].join(`
+
+`),b=new Error(j);throw b.name="CommandTimeoutError",b}return{stdout:s.stdout?.trim()||"",stderr:s.stderr?.trim()||s.message,exitCode:s.code||1}}},"execCommand"),writeFile:n(async(o,e,t={})=>{let{mode:r="0644",encoding:i="utf8"}=t;await d.promises.mkdir(C.dirname(o),{recursive:!0}),await d.promises.writeFile(o,e,{encoding:i}),await d.promises.chmod(o,r)},"writeFile"),readFile:n(async o=>await d.promises.readFile(o,"utf8"),"readFile"),fileExists:n(async o=>{try{return await d.promises.access(o),!0}catch{return!1}},"fileExists"),downloadFile:n(async function o(e,t){return new Promise((r,i)=>{let s=C.dirname(t);d.promises.mkdir(s,{recursive:!0}).then(()=>{let a=(0,d.createWriteStream)(t);(e.startsWith("https:")?V:U).get(e,l=>{if(l.statusCode===200)l.pipe(a),a.on("finish",()=>{a.close(),r(t)});else if(l.statusCode===301||l.statusCode===302){let m=l.headers.location;m?r(o(m,t)):i(new Error(`Redirect without location header: ${l.statusCode}`))}else i(new Error(`Failed to download: ${l.statusCode} ${l.statusMessage}`))}).on("error",l=>{d.promises.unlink(t).catch(()=>{}),i(l)}),a.on("error",l=>{d.promises.unlink(t).catch(()=>{}),i(l)})}).catch(i)})},"downloadFile")}}n(R,"createUtilityContext");var T=require("http");var k=class{constructor(e,t,r,i,s){this.getStatus=r;this.executeHealthCheck=i;this.getMetrics=s;this.port=e,this.logger=t.child({component:"web-server"})}static{n(this,"WebServer")}server=null;port;logger;async start(){if(this.server){this.logger.warn("Web server already running");return}return this.server=(0,T.createServer)(async(e,t)=>{if(e.method!=="GET"){t.writeHead(405,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:"Method not allowed"}));return}if(e.url==="/health")try{let r=await this.executeHealthCheck(),i=this.getStatus(),s={healthy:r,status:i.status,uptime:i.uptime,message:i.message};r?t.writeHead(200,{"Content-Type":"application/json"}):t.writeHead(503,{"Content-Type":"application/json"}),t.end(JSON.stringify(s))}catch(r){this.logger.error({error:r},"Health check endpoint error"),t.writeHead(500,{"Content-Type":"application/json"}),t.end(JSON.stringify({healthy:!1,error:r instanceof Error?r.message:"Internal server error"}))}else if(e.url==="/metrics")try{let r=await this.getMetrics();t.writeHead(200,{"Content-Type":"text/plain; version=0.0.4"}),t.end(r)}catch(r){this.logger.error({error:r},"Metrics endpoint error"),t.writeHead(500,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:r instanceof Error?r.message:"Internal server error"}))}else t.writeHead(404,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:"Not found"}))}),new Promise((e,t)=>{this.server.once("error",r=>{this.logger.error({error:r,port:this.port},"Failed to start web server"),t(r)}),this.server.listen(this.port,()=>{e()})})}async stop(){if(this.server)return new Promise(e=>{this.server.close(()=>{this.logger.info("Web server stopped"),this.server=null,e()})})}};var S=class{static{n(this,"RiptideEntrypoint")}logger;hooks;config;isShuttingDown=!1;status={status:"starting"};startTime;heartbeatInterval;webServer;constructor(e,t,r={}){this.hooks=e,this.config=t,this.startTime=Date.now(),this.logger=P({serviceName:t.service.name,level:r.logLevel||t.logging?.level||"info",format:process.env.NODE_ENV==="production"?"json":t.logging?.format||"pretty"}),this.setupGlobalErrorHandlers(),this.setupSignalHandlers()}async start(){try{let e=this.config.service.version||"unknown",t=process.env.NODE_ENV||"production";this.logger.info({version:e,environment:t},`Starting ${this.config.service.name}`),await this.processSecrets(),await this.executeHook("start"),await this.startWebServer(this.config.health?.port||3e3),this.startHeartbeat(),this.status={status:"healthy",uptime:Date.now()-this.startTime,message:"Service started successfully"},this.logger.info({service:this.config.service.name},`${this.config.service.name} service is ready`),await this.waitForShutdown()}catch(e){this.logger.error({error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0},`Failed to start ${this.config.service.name} service`),this.status={status:"unhealthy",message:e instanceof Error?e.message:String(e)},y(e)?(this.logger.error(`Exiting with code ${e.exitCode} (${e.name})`),process.exit(e.exitCode)):process.exit(1)}}async processSecrets(){if(!this.hooks.installSecrets){this.logger.info("No installSecrets hook, continuing...");return}this.logger.info("Installing secrets...");try{await this.executeHook("installSecrets")}catch(e){throw this.logger.error({error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0,hookName:"installSecrets"},"Failed to install secrets"),e}}async executeHook(e){let t=this.hooks[e];if(typeof t!="function")throw new Error(`Required hook '${e}' not found`);let r=this.createHookContext(),i=Date.now();try{let s=await t(r),a=Date.now()-i;return this.logger.debug(`Hook ${e} completed in ${a}ms`),s}catch(s){let a=Date.now()-i;throw this.logger.error({hookName:e,duration:a,error:s instanceof Error?s.message:String(s),stack:s instanceof Error?s.stack:void 0},"Hook threw an exception, will not continue"),s}}async executeHookSafely(e){if(typeof this.hooks[e]!="function")return this.logger.debug(`Optional hook '${e}' not found, skipping`),null;try{return await this.executeHook(e)}catch(r){return this.logger.warn({hookName:e,error:r instanceof Error?r.message:String(r)},"Optional hook execution failed but continuing"),null}}createHookContext(){return{config:this.config,logger:this.logger,env:process.env,utils:R()}}setupGlobalErrorHandlers(){process.on("uncaughtException",e=>{this.logger.error({error:e.message,stack:e.stack},"Uncaught exception"),y(e)?(this.logger.info(`Exiting with code ${e.exitCode} (${e.name}) from unhandled exception`),process.exit(e.exitCode)):(this.logger.error("Exiting with code 1 due to unhandled exception"),process.exit(1))}),process.on("unhandledRejection",(e,t)=>{this.logger.error({reason:e,promise:t},"Unhandled promise rejection"),y(e)?(this.logger.info(`Exiting with code ${e.exitCode} (${e.name}) from unhandled rejection`),process.exit(e.exitCode)):(this.logger.error("Exiting with code 1 due to unhandled promise rejection"),process.exit(1))})}setupSignalHandlers(){let e=n(async t=>{this.isShuttingDown&&(this.logger.warn("Force shutdown signal received"),process.exit(1)),this.isShuttingDown=!0,this.status={status:"stopping",message:`Received ${t} signal`},this.logger.info(`${t} signal received, starting graceful shutdown...`);try{this.heartbeatInterval&&clearInterval(this.heartbeatInterval),this.webServer&&await this.webServer.stop(),await this.executeHookSafely("stop"),this.status={status:"stopped",message:"Graceful shutdown completed"},this.logger.info("Graceful shutdown completed"),process.exit(0)}catch(r){this.logger.error({error:r instanceof Error?r.message:String(r)},"Error during graceful shutdown"),process.exit(1)}},"gracefulShutdown");process.on("SIGTERM",()=>e("SIGTERM")),process.on("SIGINT",()=>e("SIGINT"))}startHeartbeat(){if(!this.hooks.heartbeat){this.logger.info("No heartbeat hook defined, skipping heartbeat");return}if(!this.config.heartbeat?.enabled){this.logger.info("Heartbeat disabled in config, skipping...");return}let e=this.config.heartbeat?.interval||6e4;this.logger.info({interval:e},"Starting heartbeat");let t=!1;this.heartbeatInterval=setInterval(async()=>{if(t){this.logger.info("Heartbeat still executing, skipping this interval");return}t=!0;try{let r=await this.executeHookSafely("heartbeat");if(r===null){this.logger.info("Heartbeat hook returned null, skipping heartbeat");return}await this.pingSonar(r)}catch(r){this.logger.warn({error:r instanceof Error?r.message:String(r)},"Heartbeat execution failed")}finally{t=!1}},e)}async pingSonar(e){let t=process.env.SONAR_API_URL,r=process.env.SONAR_API_KEY,i=process.env.NOMAD_JOB_NAME;if(!t||!r||!i){this.logger.info({hasUrl:!!t,hasKey:!!r,hasJobId:!!i},"Sonar API configuration incomplete, skipping heartbeat send");return}let s=Math.floor(Date.now()/1e3),a={entity_id:i,client_timestamp:s,metadata:e};try{this.logger.info({payload:a,sonarUrl:t,sonarApiKey:r,nomadJobId:i},"Sending heartbeat to Sonar API");let c=await fetch(`${t}/api/v1/heartbeat`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${r}`},body:JSON.stringify(a)});if(!c.ok){let p=await c.text();this.logger.warn({status:c.status,error:p,entity_id:i},"Sonar API heartbeat failed")}}catch(c){this.logger.error({error:c instanceof Error?c.message:String(c),errorType:c?.constructor?.name,errorCause:c instanceof Error&&"cause"in c?c.cause:void 0,stack:c instanceof Error?c.stack:void 0,url:`${t}/api/v1/heartbeat`,entity_id:i},"Failed to send heartbeat to Sonar API")}}async startWebServer(e){this.webServer=new k(e,this.logger,()=>({...this.status,uptime:Date.now()-this.startTime}),async()=>await this.executeHookSafely("health")===!0,async()=>await this.getMetrics());try{await this.webServer.start()}catch(t){this.logger.error({error:t,port:e},"Failed to start web server")}}async waitForShutdown(){return new Promise(e=>{let t=n(()=>{this.isShuttingDown?e():setTimeout(t,100)},"checkShutdown");t()})}async getMetrics(){if(!this.hooks.metrics)return{uptime:Date.now()-this.startTime,status:this.status.status};try{return await this.executeHookSafely("metrics")}catch{return{uptime:Date.now()-this.startTime,status:this.status.status}}}};var f=u(require("fs/promises")),h=u(require("path"));var E=class{constructor(e){this.logger=e}static{n(this,"ServiceScaffolder")}async scaffold(e){let{serviceName:t,targetPath:r=".",template:i="basic",description:s}=e,a=h.join(r,t);this.logger.info(`Creating new Coral Reef service: ${t}`),this.logger.info(`Template: ${i}`),this.logger.info(`Location: ${a}`),await this.createDirectoryStructure(a),await this.createPackageJson(a,t,s),await this.createRiptideConfig(a,t,s),await this.createTsConfig(a),await this.createTsupConfig(a),await this.createHooks(a,i),await this.createDockerfile(a,t),this.logger.info("\u2705 Service scaffolding complete!"),this.showNextSteps(t,a)}async createDirectoryStructure(e){await f.mkdir(h.join(e,"src"),{recursive:!0})}async createPackageJson(e,t,r){let i={name:`reef-${t}`,version:"1.0.0",description:r||`${t} service for Coral Reef`,main:"dist/hooks.js",scripts:{build:"tsc --noEmit && tsup","build:docker":`cd ../../../.. && docker build --platform \${DOCKER_PLATFORM:-linux/amd64} --progress=plain -t reef-${t} -f apps/coral-reef/services/${t}/Dockerfile .`,clean:"rm -rf dist",start:"npx @deeep-network/riptide start --hooks dist/hooks.js",validate:"pnpm run build && npx @deeep-network/riptide validate --hooks dist/hooks.js","type-check":"tsc --noEmit"},dependencies:{"@deeep-network/riptide":"workspace:*"},devDependencies:{typescript:"^5.8.3",tsup:"^8.5.0","@types/node":"^20.0.0"},engines:{node:">=22.0.0"}};await f.writeFile(h.join(e,"package.json"),JSON.stringify(i,null,2))}async createRiptideConfig(e,t,r){let i={service:{name:t,version:"1.0.0",description:r||`${t} service`},logging:{level:"info"}};await f.writeFile(h.join(e,"riptide.config.json"),JSON.stringify(i,null,2))}async createTsConfig(e){let t={extends:"../../../../tsconfig.json",compilerOptions:{outDir:"./dist",rootDir:"./src",declaration:!0,declarationMap:!0,sourceMap:!0},include:["src/**/*"],exclude:["dist","node_modules"]};await f.writeFile(h.join(e,"tsconfig.json"),JSON.stringify(t,null,2))}async createTsupConfig(e){await f.writeFile(h.join(e,"tsup.config.ts"),`import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/hooks.ts'],
+  format: ['cjs'],
+  target: 'node22',
+  outDir: 'dist',
+  clean: true,
+  minify: false,
+  sourcemap: true
+})
+`)}async createHooks(e,t){let r="";switch(t){case"with-secrets":r=this.getHooksWithSecrets();break;case"with-process":r=this.getHooksWithProcess();break;case"with-metrics":r=this.getHooksWithMetrics();break;default:r=this.getBasicHooks()}await f.writeFile(h.join(e,"src","hooks.ts"),r)}getBasicHooks(){return`import type { HookContext } from '@deeep-network/riptide'
+
+module.exports = {
+  installSecrets: async ({ logger }: HookContext) => {
+    logger.info('Installing secrets')
+    return { success: true }
+  },
+
+  start: async ({ logger }: HookContext) => {
+    logger.info('Service starting')
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}getHooksWithSecrets(){return`import type { HookContext } from '@deeep-network/riptide'
+import {
+  MissingSecretError,
+  InvalidSecretError,
+  DiagnoseRequiredError
+} from '@deeep-network/riptide'
+
+module.exports = {
+  installSecrets: async ({ env, logger }: HookContext) => {
+    logger.info('Validating secrets')
+    
+    const apiKey = env.API_KEY
+    if (!apiKey) {
+      throw new MissingSecretError('API_KEY is required')
+    }
+
+    try {
+      const response = await fetch('https://api.example.com/validate', {
+        headers: { 'x-api-key': apiKey }
+      })
+
+      if (response.status === 401) {
+        throw new InvalidSecretError('Invalid API key')
+      }
+
+      if (!response.ok) {
+        throw new DiagnoseRequiredError(\`API returned \${response.status}\`)
+      }
+
+      logger.info('Secrets validated successfully')
+      return { success: true }
+    } catch (error) {
+      if (error instanceof Error && 'code' in error) {
+        throw new DiagnoseRequiredError(\`Network error: \${error.message}\`)
+      }
+      throw error
+    }
+  },
+
+  start: async ({ env, logger }: HookContext) => {
+    const apiKey = env.API_KEY
+    if (!apiKey) {
+      throw new MissingSecretError('API_KEY is required')
+    }
+
+    logger.info('Service starting with validated API key')
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  heartbeat: async ({ logger }: HookContext) => {
+    return {
+      service: 'your-service',
+      status: 'healthy',
+      timestamp: new Date().toISOString()
+    }
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}getHooksWithProcess(){return`import type { HookContext } from '@deeep-network/riptide'
+import { spawn, ChildProcess } from 'child_process'
+import { MissingSecretError } from '@deeep-network/riptide'
+
+let serviceProcess: ChildProcess | null = null
+
+module.exports = {
+  installSecrets: async ({ env, logger }: HookContext) => {
+    logger.info('Checking required configuration')
+    
+    if (!env.SERVICE_CONFIG) {
+      throw new MissingSecretError('SERVICE_CONFIG is required')
+    }
+
+    return { success: true }
+  },
+
+  start: async ({ env, logger }: HookContext) => {
+    logger.info('Starting service process')
+    
+    return new Promise((resolve, reject) => {
+      serviceProcess = spawn('/path/to/binary', [env.SERVICE_CONFIG || ''], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+
+      serviceProcess.on('spawn', () => {
+        logger.info(\`Service process started with PID: \${serviceProcess?.pid}\`)
+        resolve()
+      })
+
+      serviceProcess.on('error', (error) => {
+        logger.error(\`Failed to start service process: \${error.message}\`)
+        reject(error)
+      })
+
+      serviceProcess.stdout?.on('data', (data) => {
+        logger.info(\`[SERVICE] \${data.toString().trim()}\`)
+      })
+
+      serviceProcess.stderr?.on('data', (data) => {
+        logger.error(\`[SERVICE ERROR] \${data.toString().trim()}\`)
+      })
+
+      serviceProcess.unref()
+    })
+  },
+
+  health: async ({ logger, utils }: HookContext) => {
+    logger.debug('Checking service health')
+    
+    if (!serviceProcess || !serviceProcess.pid) {
+      return false
+    }
+
+    try {
+      process.kill(serviceProcess.pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  },
+
+  stop: async ({ logger, utils }: HookContext) => {
+    logger.info('Stopping service process')
+    
+    if (serviceProcess && serviceProcess.pid) {
+      try {
+        process.kill(serviceProcess.pid, 'SIGTERM')
+        await utils.sleep(2000)
+        
+        try {
+          process.kill(serviceProcess.pid, 0)
+          process.kill(serviceProcess.pid, 'SIGKILL')
+          logger.warn('Had to force kill service process')
+        } catch {
+          logger.info('Service process stopped gracefully')
+        }
+      } catch (error) {
+        logger.debug('Service process already stopped')
+      }
+    }
+    
+    serviceProcess = null
+  }
+}
+`}getHooksWithMetrics(){return`import type { HookContext } from '@deeep-network/riptide'
+
+let requestCount = 0
+let errorCount = 0
+let serviceStartTime = Date.now()
+
+module.exports = {
+  installSecrets: async ({ logger }: HookContext) => {
+    logger.info('Installing secrets')
+    return { success: true }
+  },
+
+  start: async ({ logger }: HookContext) => {
+    logger.info('Service starting')
+    serviceStartTime = Date.now()
+    
+    setInterval(() => {
+      requestCount += Math.floor(Math.random() * 10)
+      if (Math.random() < 0.1) errorCount++
+    }, 5000)
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  heartbeat: async () => {
+    return {
+      service: 'your-service',
+      status: 'healthy',
+      uptime_seconds: Math.floor((Date.now() - serviceStartTime) / 1000),
+      request_count: requestCount,
+      error_count: errorCount
+    }
+  },
+
+  metrics: async () => {
+    const uptime = Math.floor((Date.now() - serviceStartTime) / 1000)
+    
+    let output = ''
+    output += '# HELP service_uptime_seconds Time since service started\\n'
+    output += '# TYPE service_uptime_seconds gauge\\n'
+    output += \`service_uptime_seconds \${uptime}\\n\\n\`
+    
+    output += '# HELP service_requests_total Total requests processed\\n'
+    output += '# TYPE service_requests_total counter\\n'
+    output += \`service_requests_total \${requestCount}\\n\\n\`
+    
+    output += '# HELP service_errors_total Total errors encountered\\n'
+    output += '# TYPE service_errors_total counter\\n'
+    output += \`service_errors_total \${errorCount}\\n\`
+    
+    return output
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}async createDockerfile(e,t){let r=`# ${t} Service
+
+# ----------------------------------------
+# Base 
+# ----------------------------------------
+FROM node:22-alpine AS base
+RUN apk add --no-cache libc6-compat
+RUN npm install -g pnpm@10.8.0 turbo@2.5.0
+
+# ----------------------------------------
+# Turbo Pruner
+# ----------------------------------------
+FROM base AS pruner
+WORKDIR /app
+COPY . .
+RUN turbo prune reef-${t} --docker
+
+# ----------------------------------------
+# Turbo Builder and Pnpm Deployment
+# ----------------------------------------
+FROM base AS builder
+WORKDIR /app
+COPY --from=pruner /app/out/full/ .
+RUN pnpm install 
+COPY turbo.json tsconfig.json .
+RUN pnpm turbo run build --filter=reef-${t}... 
+
+# Create pnpm deployment
+RUN pnpm deploy --prod --filter reef-${t} deploy
+
+# ----------------------------------------
+# Minimal Runner
+# ----------------------------------------
+FROM node:22-alpine AS runner
+
+# Create application user
+RUN addgroup -g 1001 app && \\
+    adduser -u 1001 -G app -D app
+
+WORKDIR /app
+
+# Copy deployment artifacts
+COPY --from=builder --chown=app:app /app/deploy/dist ./dist
+COPY --from=builder --chown=app:app /app/deploy/node_modules ./node_modules
+COPY --from=builder --chown=app:app /app/deploy/package.json ./package.json
+COPY --from=builder --chown=app:app /app/deploy/riptide.config.json ./riptide.config.json
+
+# Create necessary directories
+RUN mkdir -p logs data tmp && chown -R app:app logs data tmp
+
+# Switch to non-root user
+USER app
+
+# Set environment
+ENV NODE_ENV=production
+
+# Start command
+CMD ["npm", "start"]
+`;await f.writeFile(h.join(e,"Dockerfile"),r)}showNextSteps(e,t){console.log(`
+Next steps:
+-----------
+1. Navigate to your service:
+   cd ${t}
+
+2. Install dependencies:
+   pnpm install
+
+3. Build the service:
+   pnpm run build
+
+4. Validate the hooks:
+   pnpm run validate
+
+5. Build Docker image:
+   pnpm run build:docker
+
+6. Run locally:
+   docker run -e API_KEY=your-key reef-${e}
+
+7. Add to turbo.json if needed for monorepo builds
+
+8. Customize the hooks in src/hooks.ts for your specific requirements
+`)}};async function I(o,e,t={}){await new E(o).scaffold({serviceName:e,...t})}n(I,"initService");var g=(0,M.default)({level:process.env.LOG_LEVEL||"info",transport:{target:"pino-pretty"}});async function W(){try{let o=process.argv[2];if(o==="--help"||o==="-h"||o==="help"){D();return}if(o==="--version"||o==="-v"||o==="version"){await G();return}let e=v("--config")||v("-c")||"./riptide.config.json",t=v("--hooks")||v("-h")||"./hooks.js";switch(o){case"init":await z();break;case"start":await $(e,t);break;case"validate":await K(e,t);break;case"health":await Y();break;case"status":await B();break;default:o?(g.error(`Unknown command: ${o}`),D(),process.exit(1)):await $(e,t)}}catch(o){g.error({error:o},"CLI command failed"),process.exit(1)}}n(W,"main");function v(o){let e=process.argv.indexOf(o);if(e>=0&&e+1<process.argv.length)return process.argv[e+1]}n(v,"getArgValue");function D(){console.log(`
+Riptide - Self-contained service lifecycle management
+
+USAGE:
+  npx riptide [COMMAND] [OPTIONS]
+
+COMMANDS:
+  init <name>         Create a new Coral Reef service
+  start               Start the service (default)
+  validate            Validate configuration and hooks
+  health              Check service health
+  status              Show service status
+  help, --help, -h    Show this help message
+  version, --version  Show version information
+
+INIT OPTIONS:
+  --template TYPE     Template to use: basic, with-secrets, with-process, with-metrics (default: basic)
+  --path PATH         Directory to create service in (default: current directory)
+  --description DESC  Service description
+
+OPTIONS:
+  --config, -c PATH   Path to configuration file (default: ./riptide.config.json)
+  --hooks PATH        Path to hooks file (default: ./hooks.js)
+
+EXAMPLES:
+  npx riptide init my-service    # Create new service
+  npx riptide init my-service --template with-secrets
+  npx riptide start              # Start service
+  npx riptide validate           # Validate config and hooks
+  npx riptide health             # Check service health
+`)}n(D,"showHelp");async function G(){let o=await import("fs/promises"),t=(await import("path")).resolve(__dirname,"../package.json"),r=await o.readFile(t,"utf-8"),i=JSON.parse(r);console.log(`@deeep-network/riptide v${i.version}`)}n(G,"showVersion");async function $(o,e){try{let t=await import("fs/promises"),r=await import("path"),i=await t.readFile(o,"utf-8"),s=JSON.parse(i),c=await import(r.resolve(process.cwd(),e)),p=c.default||c;await new S(p,s,{}).start()}catch(t){g.error({error:t},"Failed to start service"),process.exit(1)}}n($,"startService");async function K(o,e){g.info("Validating riptide configuration and hooks...");try{let t=await import("fs/promises"),r=await import("path"),i=await t.readFile(o,"utf-8"),s=JSON.parse(i);g.info({config:s},"Configuration loaded successfully");let c=await import(r.resolve(process.cwd(),e)),p=c.default||c;g.info({availableHooks:Object.keys(p)},"Hooks loaded successfully"),g.info("\u2705 Validation completed successfully"),process.exit(0)}catch(t){g.error({error:t},"\u274C Validation failed"),process.exit(1)}}n(K,"validateService");async function Y(){try{let e=await(await fetch("http://localhost:3000/health")).json();console.log("Health Status:",JSON.stringify(e,null,2)),e.status==="healthy"?process.exit(0):process.exit(1)}catch(o){g.error({error:o},"Failed to check health"),process.exit(1)}}n(Y,"checkHealth");async function B(){try{let e=await(await fetch("http://localhost:3000/status")).json();console.log("Service Status:",JSON.stringify(e,null,2))}catch(o){g.error({error:o},"Failed to get status"),process.exit(1)}}n(B,"showStatus");async function z(){let o=process.argv[3];o||(g.error("Service name is required"),console.log("Usage: npx riptide init <service-name>"),process.exit(1)),/^[a-z0-9-]+$/.test(o)||(g.error("Service name must contain only lowercase letters, numbers, and hyphens"),process.exit(1));let e=v("--template")||"basic",t=v("--path")||"apps/coral-reef/services",r=v("--description"),i=["basic","with-secrets","with-process","with-metrics"];i.includes(e)||(g.error(`Invalid template: ${e}`),console.log(`Valid templates: ${i.join(", ")}`),process.exit(1));try{await I(g,o,{targetPath:t,template:e,description:r}),process.exit(0)}catch(s){g.error({error:s},"Failed to initialize service"),process.exit(1)}}n(z,"initServiceCommand");W();

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { Logger } from 'pino';
+
+interface HookContext {
+    config: ServiceConfig;
+    logger: Logger;
+    env: NodeJS.ProcessEnv;
+    utils: UtilityContext;
+    [key: string]: any;
+}
+interface UtilityContext {
+    sleep: (ms: number) => Promise<void>;
+    retry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+    execCommand: (command: string, options?: ExecOptions) => Promise<ExecResult>;
+    writeFile: (path: string, content: string, options?: WriteFileOptions) => Promise<void>;
+    readFile: (path: string) => Promise<string>;
+    fileExists: (path: string) => Promise<boolean>;
+    downloadFile: (url: string, destination: string) => Promise<string>;
+}
+interface RetryOptions {
+    maxAttempts?: number;
+    delay?: number;
+    backoffMultiplier?: number;
+    maxDelay?: number;
+}
+interface ExecOptions {
+    timeout?: number;
+    user?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface WriteFileOptions {
+    mode?: string;
+    encoding?: BufferEncoding;
+}
+interface HookModule {
+    installSecrets?: (context: HookContext) => Promise<{
+        success: boolean;
+        transformedSecrets?: Record<string, string>;
+    }>;
+    start: (context: HookContext) => Promise<void>;
+    stop?: (context: HookContext) => Promise<void>;
+    health: (context: HookContext) => Promise<boolean>;
+    heartbeat?: (context: HookContext) => Promise<Record<string, any> | null>;
+    status?: (context: HookContext) => Promise<ServiceStatus>;
+    metrics?: (context: HookContext) => Promise<ServiceMetrics>;
+}
+interface ServiceConfig {
+    service: {
+        name: string;
+        version?: string;
+        description?: string;
+    };
+    health?: {
+        port?: number;
+    };
+    heartbeat?: {
+        interval?: number;
+        enabled?: boolean;
+    };
+    logging?: {
+        level?: 'debug' | 'info' | 'warn' | 'error';
+        format?: 'json' | 'pretty';
+    };
+}
+interface ServiceStatus {
+    status: 'starting' | 'healthy' | 'unhealthy' | 'stopping' | 'stopped';
+    uptime?: number;
+    message?: string;
+    details?: Record<string, any>;
+}
+interface ServiceMetrics {
+    [key: string]: number | string | boolean;
+}
+interface RiptideEntrypointOptions {
+    configPath?: string;
+    hooksPath?: string;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    dryRun?: boolean;
+}
+
+declare class RiptideEntrypoint {
+    private logger;
+    private hooks;
+    private config;
+    private isShuttingDown;
+    private status;
+    private startTime;
+    private heartbeatInterval?;
+    private webServer?;
+    constructor(hooks: HookModule, config: ServiceConfig, options?: RiptideEntrypointOptions);
+    start(): Promise<void>;
+    private processSecrets;
+    private executeHook;
+    private executeHookSafely;
+    private createHookContext;
+    private setupGlobalErrorHandlers;
+    private setupSignalHandlers;
+    private startHeartbeat;
+    private pingSonar;
+    private startWebServer;
+    private waitForShutdown;
+    getMetrics(): Promise<any>;
+}
+
+declare function loadConfig(configPath: string): Promise<ServiceConfig>;
+declare function loadHooks(hooksPath: string): Promise<HookModule>;
+declare function validateConfig(config: ServiceConfig): void;
+declare function getDefaultConfig(): Partial<ServiceConfig>;
+declare function mergeConfigs(base: Partial<ServiceConfig>, override: Partial<ServiceConfig>): ServiceConfig;
+
+interface LoggerOptions {
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    format?: 'json' | 'pretty';
+    serviceName: string;
+}
+declare function createLogger(options: LoggerOptions): Logger;
+declare function createChildLogger(parentLogger: Logger, context: Record<string, any>): Logger;
+
+declare function createUtilityContext(): UtilityContext;
+declare function redactSecret(secret: string): string;
+declare function parseEnvironmentVariables(input: string): Record<string, string>;
+declare function expandEnvironmentVariables(input: string, env?: Record<string, string | undefined>): string;
+
+interface ScaffoldOptions {
+    serviceName: string;
+    targetPath?: string;
+    template?: 'basic' | 'with-secrets' | 'with-process' | 'with-metrics';
+    description?: string;
+}
+declare class ServiceScaffolder {
+    private logger;
+    constructor(logger: Logger);
+    scaffold(options: ScaffoldOptions): Promise<void>;
+    private createDirectoryStructure;
+    private createPackageJson;
+    private createRiptideConfig;
+    private createTsConfig;
+    private createTsupConfig;
+    private createHooks;
+    private getBasicHooks;
+    private getHooksWithSecrets;
+    private getHooksWithProcess;
+    private getHooksWithMetrics;
+    private createDockerfile;
+    private showNextSteps;
+}
+declare function initService(logger: Logger, serviceName: string, options?: Partial<ScaffoldOptions>): Promise<void>;
+
+/**
+ * Custom error classes for Riptide Entrypoint
+ * These errors map to specific exit codes for container orchestration
+ */
+/**
+ * Base class for all Riptide custom errors
+ * Provides a reliable way to identify riptide-specific errors
+ */
+declare abstract class RiptideError extends Error {
+    abstract readonly exitCode: number;
+    constructor(message: string);
+}
+/**
+ * Error indicating that manual intervention is required
+ * Exit code: 3
+ */
+declare class DiagnoseRequiredError extends RiptideError {
+    readonly exitCode = 3;
+    constructor(message: string);
+}
+/**
+ * Error indicating that a required secret is missing
+ * Exit code: 4
+ */
+declare class MissingSecretError extends RiptideError {
+    readonly exitCode = 4;
+    constructor(message: string);
+}
+/**
+ * Error indicating that a secret is invalid or malformed
+ * Exit code: 5
+ */
+declare class InvalidSecretError extends RiptideError {
+    readonly exitCode = 5;
+    constructor(message: string);
+}
+/**
+ * Error indicating that the service is already running somewhere and we can't start it again
+ * Exit code: 6
+ */
+declare class AlreadyRunningError extends RiptideError {
+    readonly exitCode = 6;
+    constructor(message: string);
+}
+/**
+ * Type guards for Riptide errors that work across module boundaries
+ */
+declare function isRiptideError(error: unknown): error is RiptideError;
+declare function isDiagnoseRequiredError(error: unknown): error is DiagnoseRequiredError;
+declare function isMissingSecretError(error: unknown): error is MissingSecretError;
+declare function isInvalidSecretError(error: unknown): error is InvalidSecretError;
+declare function isAlreadyRunningError(error: unknown): error is AlreadyRunningError;
+
+export { AlreadyRunningError, DiagnoseRequiredError, type ExecOptions, type ExecResult, type HookContext, type HookModule, InvalidSecretError, MissingSecretError, type RetryOptions, RiptideEntrypoint, type RiptideEntrypointOptions, RiptideError, type ScaffoldOptions, type ServiceConfig, type ServiceMetrics, ServiceScaffolder, type ServiceStatus, type UtilityContext, type WriteFileOptions, createChildLogger, createLogger, createUtilityContext, expandEnvironmentVariables, getDefaultConfig, initService, isAlreadyRunningError, isDiagnoseRequiredError, isInvalidSecretError, isMissingSecretError, isRiptideError, loadConfig, loadHooks, mergeConfigs, parseEnvironmentVariables, redactSecret, validateConfig };

package/dist/index.js

@@ -0,0 +1,331 @@
+"use strict";var X=Object.create;var y=Object.defineProperty;var Z=Object.getOwnPropertyDescriptor;var ee=Object.getOwnPropertyNames;var te=Object.getPrototypeOf,re=Object.prototype.hasOwnProperty;var n=(r,e)=>y(r,"name",{value:e,configurable:!0});var oe=(r,e)=>{for(var t in e)y(r,t,{get:e[t],enumerable:!0})},T=(r,e,t,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of ee(e))!re.call(r,i)&&i!==t&&y(r,i,{get:()=>e[i],enumerable:!(o=Z(e,i))||o.enumerable});return r};var m=(r,e,t)=>(t=r!=null?X(te(r)):{},T(e||!r||!r.__esModule?y(t,"default",{value:r,enumerable:!0}):t,r)),ie=r=>T(y({},"__esModule",{value:!0}),r);var pe={};oe(pe,{AlreadyRunningError:()=>C,DiagnoseRequiredError:()=>S,InvalidSecretError:()=>x,MissingSecretError:()=>k,RiptideEntrypoint:()=>O,RiptideError:()=>h,ServiceScaffolder:()=>w,createChildLogger:()=>j,createLogger:()=>b,createUtilityContext:()=>P,expandEnvironmentVariables:()=>H,getDefaultConfig:()=>G,initService:()=>z,isAlreadyRunningError:()=>A,isDiagnoseRequiredError:()=>M,isInvalidSecretError:()=>N,isMissingSecretError:()=>_,isRiptideError:()=>v,loadConfig:()=>V,loadHooks:()=>Y,mergeConfigs:()=>B,parseEnvironmentVariables:()=>U,redactSecret:()=>q,validateConfig:()=>I});module.exports=ie(pe);var h=class r extends Error{static{n(this,"RiptideError")}constructor(e){super(e),Object.setPrototypeOf(this,r.prototype)}},S=class r extends h{static{n(this,"DiagnoseRequiredError")}exitCode=3;constructor(e){super(e),this.name="DiagnoseRequiredError",Object.setPrototypeOf(this,r.prototype)}},k=class r extends h{static{n(this,"MissingSecretError")}exitCode=4;constructor(e){super(e),this.name="MissingSecretError",Object.setPrototypeOf(this,r.prototype)}},x=class r extends h{static{n(this,"InvalidSecretError")}exitCode=5;constructor(e){super(e),this.name="InvalidSecretError",Object.setPrototypeOf(this,r.prototype)}},C=class r extends h{static{n(this,"AlreadyRunningError")}exitCode=6;constructor(e){super(e),this.name="AlreadyRunningError",Object.setPrototypeOf(this,r.prototype)}};function v(r){return r instanceof Error&&"exitCode"in r&&typeof r.exitCode=="number"}n(v,"isRiptideError");function M(r){return r instanceof Error&&r.name==="DiagnoseRequiredError"&&r.exitCode===3}n(M,"isDiagnoseRequiredError");function _(r){return r instanceof Error&&r.name==="MissingSecretError"&&r.exitCode===4}n(_,"isMissingSecretError");function N(r){return r instanceof Error&&r.name==="InvalidSecretError"&&r.exitCode===5}n(N,"isInvalidSecretError");function A(r){return r instanceof Error&&r.name==="AlreadyRunningError"&&r.exitCode===6}n(A,"isAlreadyRunningError");var E=m(require("pino"));function b(r){let{level:e="info",format:t="pretty",serviceName:o}=r,i={level:e,timestamp:E.default.stdTimeFunctions.isoTime,formatters:{log:n(s=>({service:o,...s}),"log"),bindings:n(s=>{let{pid:a,hostname:c,...l}=s;return l},"bindings")}};return t==="pretty"&&!process.env.NODE_ENV?.includes("prod")?(0,E.default)({...i,transport:{target:"pino-pretty",options:{colorize:!0,translateTime:"SYS:standard",ignore:"pid,hostname"}}}):(0,E.default)(i)}n(b,"createLogger");function j(r,e){return r.child(e)}n(j,"createChildLogger");var F=require("child_process"),g=require("fs"),se=m(require("http")),ne=m(require("https")),$=m(require("path")),L=require("util");var ae=(0,L.promisify)(F.exec);function P(){return{sleep:n(r=>new Promise(e=>setTimeout(e,r)),"sleep"),retry:n(async(r,e={})=>{let{maxAttempts:t=3,delay:o=1e3,backoffMultiplier:i=2,maxDelay:s=3e4}=e,a,c=o;for(let l=1;l<=t;l++)try{return await r()}catch(p){if(a=p instanceof Error?p:new Error(String(p)),l===t)throw a;await new Promise(f=>setTimeout(f,Math.min(c,s))),c*=i}throw a},"retry"),execCommand:n(async(r,e={})=>{let{timeout:t=3e4,cwd:o=process.cwd(),env:i=process.env}=e;try{let{stdout:s,stderr:a}=await ae(r,{timeout:t,cwd:o,env:{...process.env,...i}});return{stdout:s.trim(),stderr:a.trim(),exitCode:0}}catch(s){if(s.killed&&s.signal==="SIGTERM"){let c=`Command timed out after ${t/1e3}s. Consider increasing timeout if command needs more time to complete: utils.execCommand('${r}', { timeout: ${t*2} })`,l=s.stderr?.trim()||"",p=l?`${l}
+
+${c}`:c,f=[];s.stdout?.trim()&&f.push(`STDOUT: ${s.stdout.trim()}`),p&&f.push(`STDERR: ${p}`);let Q=[`Command execution timed out: ${r}`,...f].join(`
+
+`),D=new Error(Q);throw D.name="CommandTimeoutError",D}return{stdout:s.stdout?.trim()||"",stderr:s.stderr?.trim()||s.message,exitCode:s.code||1}}},"execCommand"),writeFile:n(async(r,e,t={})=>{let{mode:o="0644",encoding:i="utf8"}=t;await g.promises.mkdir($.dirname(r),{recursive:!0}),await g.promises.writeFile(r,e,{encoding:i}),await g.promises.chmod(r,o)},"writeFile"),readFile:n(async r=>await g.promises.readFile(r,"utf8"),"readFile"),fileExists:n(async r=>{try{return await g.promises.access(r),!0}catch{return!1}},"fileExists"),downloadFile:n(async function r(e,t){return new Promise((o,i)=>{let s=$.dirname(t);g.promises.mkdir(s,{recursive:!0}).then(()=>{let a=(0,g.createWriteStream)(t);(e.startsWith("https:")?ne:se).get(e,p=>{if(p.statusCode===200)p.pipe(a),a.on("finish",()=>{a.close(),o(t)});else if(p.statusCode===301||p.statusCode===302){let f=p.headers.location;f?o(r(f,t)):i(new Error(`Redirect without location header: ${p.statusCode}`))}else i(new Error(`Failed to download: ${p.statusCode} ${p.statusMessage}`))}).on("error",p=>{g.promises.unlink(t).catch(()=>{}),i(p)}),a.on("error",p=>{g.promises.unlink(t).catch(()=>{}),i(p)})}).catch(i)})},"downloadFile")}}n(P,"createUtilityContext");function q(r){return!r||r.length<=10?"[REDACTED]":`${r.slice(0,4)}...${r.slice(-4)}`}n(q,"redactSecret");function U(r){let e={},t=r.split(`
+`);for(let o of t){let i=o.trim();if(i&&!i.startsWith("#")){let[s,...a]=i.split("=");s&&a.length>0&&(e[s.trim()]=a.join("=").trim())}}return e}n(U,"parseEnvironmentVariables");function H(r,e=process.env){return r.replace(/\$\{([^}]+)\}/g,(t,o)=>e[o]||t)}n(H,"expandEnvironmentVariables");var J=require("http");var R=class{constructor(e,t,o,i,s){this.getStatus=o;this.executeHealthCheck=i;this.getMetrics=s;this.port=e,this.logger=t.child({component:"web-server"})}static{n(this,"WebServer")}server=null;port;logger;async start(){if(this.server){this.logger.warn("Web server already running");return}return this.server=(0,J.createServer)(async(e,t)=>{if(e.method!=="GET"){t.writeHead(405,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:"Method not allowed"}));return}if(e.url==="/health")try{let o=await this.executeHealthCheck(),i=this.getStatus(),s={healthy:o,status:i.status,uptime:i.uptime,message:i.message};o?t.writeHead(200,{"Content-Type":"application/json"}):t.writeHead(503,{"Content-Type":"application/json"}),t.end(JSON.stringify(s))}catch(o){this.logger.error({error:o},"Health check endpoint error"),t.writeHead(500,{"Content-Type":"application/json"}),t.end(JSON.stringify({healthy:!1,error:o instanceof Error?o.message:"Internal server error"}))}else if(e.url==="/metrics")try{let o=await this.getMetrics();t.writeHead(200,{"Content-Type":"text/plain; version=0.0.4"}),t.end(o)}catch(o){this.logger.error({error:o},"Metrics endpoint error"),t.writeHead(500,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:o instanceof Error?o.message:"Internal server error"}))}else t.writeHead(404,{"Content-Type":"application/json"}),t.end(JSON.stringify({error:"Not found"}))}),new Promise((e,t)=>{this.server.once("error",o=>{this.logger.error({error:o,port:this.port},"Failed to start web server"),t(o)}),this.server.listen(this.port,()=>{e()})})}async stop(){if(this.server)return new Promise(e=>{this.server.close(()=>{this.logger.info("Web server stopped"),this.server=null,e()})})}};var O=class{static{n(this,"RiptideEntrypoint")}logger;hooks;config;isShuttingDown=!1;status={status:"starting"};startTime;heartbeatInterval;webServer;constructor(e,t,o={}){this.hooks=e,this.config=t,this.startTime=Date.now(),this.logger=b({serviceName:t.service.name,level:o.logLevel||t.logging?.level||"info",format:process.env.NODE_ENV==="production"?"json":t.logging?.format||"pretty"}),this.setupGlobalErrorHandlers(),this.setupSignalHandlers()}async start(){try{let e=this.config.service.version||"unknown",t=process.env.NODE_ENV||"production";this.logger.info({version:e,environment:t},`Starting ${this.config.service.name}`),await this.processSecrets(),await this.executeHook("start"),await this.startWebServer(this.config.health?.port||3e3),this.startHeartbeat(),this.status={status:"healthy",uptime:Date.now()-this.startTime,message:"Service started successfully"},this.logger.info({service:this.config.service.name},`${this.config.service.name} service is ready`),await this.waitForShutdown()}catch(e){this.logger.error({error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0},`Failed to start ${this.config.service.name} service`),this.status={status:"unhealthy",message:e instanceof Error?e.message:String(e)},v(e)?(this.logger.error(`Exiting with code ${e.exitCode} (${e.name})`),process.exit(e.exitCode)):process.exit(1)}}async processSecrets(){if(!this.hooks.installSecrets){this.logger.info("No installSecrets hook, continuing...");return}this.logger.info("Installing secrets...");try{await this.executeHook("installSecrets")}catch(e){throw this.logger.error({error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0,hookName:"installSecrets"},"Failed to install secrets"),e}}async executeHook(e){let t=this.hooks[e];if(typeof t!="function")throw new Error(`Required hook '${e}' not found`);let o=this.createHookContext(),i=Date.now();try{let s=await t(o),a=Date.now()-i;return this.logger.debug(`Hook ${e} completed in ${a}ms`),s}catch(s){let a=Date.now()-i;throw this.logger.error({hookName:e,duration:a,error:s instanceof Error?s.message:String(s),stack:s instanceof Error?s.stack:void 0},"Hook threw an exception, will not continue"),s}}async executeHookSafely(e){if(typeof this.hooks[e]!="function")return this.logger.debug(`Optional hook '${e}' not found, skipping`),null;try{return await this.executeHook(e)}catch(o){return this.logger.warn({hookName:e,error:o instanceof Error?o.message:String(o)},"Optional hook execution failed but continuing"),null}}createHookContext(){return{config:this.config,logger:this.logger,env:process.env,utils:P()}}setupGlobalErrorHandlers(){process.on("uncaughtException",e=>{this.logger.error({error:e.message,stack:e.stack},"Uncaught exception"),v(e)?(this.logger.info(`Exiting with code ${e.exitCode} (${e.name}) from unhandled exception`),process.exit(e.exitCode)):(this.logger.error("Exiting with code 1 due to unhandled exception"),process.exit(1))}),process.on("unhandledRejection",(e,t)=>{this.logger.error({reason:e,promise:t},"Unhandled promise rejection"),v(e)?(this.logger.info(`Exiting with code ${e.exitCode} (${e.name}) from unhandled rejection`),process.exit(e.exitCode)):(this.logger.error("Exiting with code 1 due to unhandled promise rejection"),process.exit(1))})}setupSignalHandlers(){let e=n(async t=>{this.isShuttingDown&&(this.logger.warn("Force shutdown signal received"),process.exit(1)),this.isShuttingDown=!0,this.status={status:"stopping",message:`Received ${t} signal`},this.logger.info(`${t} signal received, starting graceful shutdown...`);try{this.heartbeatInterval&&clearInterval(this.heartbeatInterval),this.webServer&&await this.webServer.stop(),await this.executeHookSafely("stop"),this.status={status:"stopped",message:"Graceful shutdown completed"},this.logger.info("Graceful shutdown completed"),process.exit(0)}catch(o){this.logger.error({error:o instanceof Error?o.message:String(o)},"Error during graceful shutdown"),process.exit(1)}},"gracefulShutdown");process.on("SIGTERM",()=>e("SIGTERM")),process.on("SIGINT",()=>e("SIGINT"))}startHeartbeat(){if(!this.hooks.heartbeat){this.logger.info("No heartbeat hook defined, skipping heartbeat");return}if(!this.config.heartbeat?.enabled){this.logger.info("Heartbeat disabled in config, skipping...");return}let e=this.config.heartbeat?.interval||6e4;this.logger.info({interval:e},"Starting heartbeat");let t=!1;this.heartbeatInterval=setInterval(async()=>{if(t){this.logger.info("Heartbeat still executing, skipping this interval");return}t=!0;try{let o=await this.executeHookSafely("heartbeat");if(o===null){this.logger.info("Heartbeat hook returned null, skipping heartbeat");return}await this.pingSonar(o)}catch(o){this.logger.warn({error:o instanceof Error?o.message:String(o)},"Heartbeat execution failed")}finally{t=!1}},e)}async pingSonar(e){let t=process.env.SONAR_API_URL,o=process.env.SONAR_API_KEY,i=process.env.NOMAD_JOB_NAME;if(!t||!o||!i){this.logger.info({hasUrl:!!t,hasKey:!!o,hasJobId:!!i},"Sonar API configuration incomplete, skipping heartbeat send");return}let s=Math.floor(Date.now()/1e3),a={entity_id:i,client_timestamp:s,metadata:e};try{this.logger.info({payload:a,sonarUrl:t,sonarApiKey:o,nomadJobId:i},"Sending heartbeat to Sonar API");let c=await fetch(`${t}/api/v1/heartbeat`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${o}`},body:JSON.stringify(a)});if(!c.ok){let l=await c.text();this.logger.warn({status:c.status,error:l,entity_id:i},"Sonar API heartbeat failed")}}catch(c){this.logger.error({error:c instanceof Error?c.message:String(c),errorType:c?.constructor?.name,errorCause:c instanceof Error&&"cause"in c?c.cause:void 0,stack:c instanceof Error?c.stack:void 0,url:`${t}/api/v1/heartbeat`,entity_id:i},"Failed to send heartbeat to Sonar API")}}async startWebServer(e){this.webServer=new R(e,this.logger,()=>({...this.status,uptime:Date.now()-this.startTime}),async()=>await this.executeHookSafely("health")===!0,async()=>await this.getMetrics());try{await this.webServer.start()}catch(t){this.logger.error({error:t,port:e},"Failed to start web server")}}async waitForShutdown(){return new Promise(e=>{let t=n(()=>{this.isShuttingDown?e():setTimeout(t,100)},"checkShutdown");t()})}async getMetrics(){if(!this.hooks.metrics)return{uptime:Date.now()-this.startTime,status:this.status.status};try{return await this.executeHookSafely("metrics")}catch{return{uptime:Date.now()-this.startTime,status:this.status.status}}}};var W=require("fs"),K=m(require("path"));async function V(r){try{let e=await W.promises.readFile(r,"utf8"),t=JSON.parse(e),o=ce(t);return I(o),o}catch(e){throw new Error(`Failed to load config from ${r}: ${e instanceof Error?e.message:String(e)}`)}}n(V,"loadConfig");async function Y(r){try{let e=K.resolve(r);delete require.cache[e];let t=require(e);if(typeof t.start!="function")throw new Error('Hooks module must export a "start" function');return t}catch(e){throw new Error(`Failed to load hooks from ${r}: ${e instanceof Error?e.message:String(e)}`)}}n(Y,"loadHooks");function I(r){if(!r.service?.name)throw new Error("Config must have service.name");if(r.health,r.heartbeat&&r.heartbeat.interval&&r.heartbeat.interval<1e3)throw new Error("heartbeat.interval must be at least 1000ms")}n(I,"validateConfig");function ce(r,e=process.env){let t=JSON.parse(JSON.stringify(r));function o(i){if(typeof i=="string")return H(i,e);if(Array.isArray(i))return i.map(o);if(i&&typeof i=="object"){let s={};for(let[a,c]of Object.entries(i))s[a]=o(c);return s}return i}return n(o,"expandObject"),o(t)}n(ce,"expandConfigVariables");function G(){return{health:{port:3e3},heartbeat:{interval:6e4,enabled:!1},logging:{level:"info",format:"pretty"}}}n(G,"getDefaultConfig");function B(r,e){function t(i,s){if(s&&typeof s=="object"&&!Array.isArray(s))for(let a in s)s.hasOwnProperty(a)&&(i[a]&&typeof i[a]=="object"&&!Array.isArray(i[a])?i[a]=t(i[a],s[a]):i[a]=s[a]);return i}n(t,"deepMerge");let o=t({...r},e);return I(o),o}n(B,"mergeConfigs");var d=m(require("fs/promises")),u=m(require("path"));var w=class{constructor(e){this.logger=e}static{n(this,"ServiceScaffolder")}async scaffold(e){let{serviceName:t,targetPath:o=".",template:i="basic",description:s}=e,a=u.join(o,t);this.logger.info(`Creating new Coral Reef service: ${t}`),this.logger.info(`Template: ${i}`),this.logger.info(`Location: ${a}`),await this.createDirectoryStructure(a),await this.createPackageJson(a,t,s),await this.createRiptideConfig(a,t,s),await this.createTsConfig(a),await this.createTsupConfig(a),await this.createHooks(a,i),await this.createDockerfile(a,t),this.logger.info("\u2705 Service scaffolding complete!"),this.showNextSteps(t,a)}async createDirectoryStructure(e){await d.mkdir(u.join(e,"src"),{recursive:!0})}async createPackageJson(e,t,o){let i={name:`reef-${t}`,version:"1.0.0",description:o||`${t} service for Coral Reef`,main:"dist/hooks.js",scripts:{build:"tsc --noEmit && tsup","build:docker":`cd ../../../.. && docker build --platform \${DOCKER_PLATFORM:-linux/amd64} --progress=plain -t reef-${t} -f apps/coral-reef/services/${t}/Dockerfile .`,clean:"rm -rf dist",start:"npx @deeep-network/riptide start --hooks dist/hooks.js",validate:"pnpm run build && npx @deeep-network/riptide validate --hooks dist/hooks.js","type-check":"tsc --noEmit"},dependencies:{"@deeep-network/riptide":"workspace:*"},devDependencies:{typescript:"^5.8.3",tsup:"^8.5.0","@types/node":"^20.0.0"},engines:{node:">=22.0.0"}};await d.writeFile(u.join(e,"package.json"),JSON.stringify(i,null,2))}async createRiptideConfig(e,t,o){let i={service:{name:t,version:"1.0.0",description:o||`${t} service`},logging:{level:"info"}};await d.writeFile(u.join(e,"riptide.config.json"),JSON.stringify(i,null,2))}async createTsConfig(e){let t={extends:"../../../../tsconfig.json",compilerOptions:{outDir:"./dist",rootDir:"./src",declaration:!0,declarationMap:!0,sourceMap:!0},include:["src/**/*"],exclude:["dist","node_modules"]};await d.writeFile(u.join(e,"tsconfig.json"),JSON.stringify(t,null,2))}async createTsupConfig(e){await d.writeFile(u.join(e,"tsup.config.ts"),`import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/hooks.ts'],
+  format: ['cjs'],
+  target: 'node22',
+  outDir: 'dist',
+  clean: true,
+  minify: false,
+  sourcemap: true
+})
+`)}async createHooks(e,t){let o="";switch(t){case"with-secrets":o=this.getHooksWithSecrets();break;case"with-process":o=this.getHooksWithProcess();break;case"with-metrics":o=this.getHooksWithMetrics();break;default:o=this.getBasicHooks()}await d.writeFile(u.join(e,"src","hooks.ts"),o)}getBasicHooks(){return`import type { HookContext } from '@deeep-network/riptide'
+
+module.exports = {
+  installSecrets: async ({ logger }: HookContext) => {
+    logger.info('Installing secrets')
+    return { success: true }
+  },
+
+  start: async ({ logger }: HookContext) => {
+    logger.info('Service starting')
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}getHooksWithSecrets(){return`import type { HookContext } from '@deeep-network/riptide'
+import {
+  MissingSecretError,
+  InvalidSecretError,
+  DiagnoseRequiredError
+} from '@deeep-network/riptide'
+
+module.exports = {
+  installSecrets: async ({ env, logger }: HookContext) => {
+    logger.info('Validating secrets')
+    
+    const apiKey = env.API_KEY
+    if (!apiKey) {
+      throw new MissingSecretError('API_KEY is required')
+    }
+
+    try {
+      const response = await fetch('https://api.example.com/validate', {
+        headers: { 'x-api-key': apiKey }
+      })
+
+      if (response.status === 401) {
+        throw new InvalidSecretError('Invalid API key')
+      }
+
+      if (!response.ok) {
+        throw new DiagnoseRequiredError(\`API returned \${response.status}\`)
+      }
+
+      logger.info('Secrets validated successfully')
+      return { success: true }
+    } catch (error) {
+      if (error instanceof Error && 'code' in error) {
+        throw new DiagnoseRequiredError(\`Network error: \${error.message}\`)
+      }
+      throw error
+    }
+  },
+
+  start: async ({ env, logger }: HookContext) => {
+    const apiKey = env.API_KEY
+    if (!apiKey) {
+      throw new MissingSecretError('API_KEY is required')
+    }
+
+    logger.info('Service starting with validated API key')
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  heartbeat: async ({ logger }: HookContext) => {
+    return {
+      service: 'your-service',
+      status: 'healthy',
+      timestamp: new Date().toISOString()
+    }
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}getHooksWithProcess(){return`import type { HookContext } from '@deeep-network/riptide'
+import { spawn, ChildProcess } from 'child_process'
+import { MissingSecretError } from '@deeep-network/riptide'
+
+let serviceProcess: ChildProcess | null = null
+
+module.exports = {
+  installSecrets: async ({ env, logger }: HookContext) => {
+    logger.info('Checking required configuration')
+    
+    if (!env.SERVICE_CONFIG) {
+      throw new MissingSecretError('SERVICE_CONFIG is required')
+    }
+
+    return { success: true }
+  },
+
+  start: async ({ env, logger }: HookContext) => {
+    logger.info('Starting service process')
+    
+    return new Promise((resolve, reject) => {
+      serviceProcess = spawn('/path/to/binary', [env.SERVICE_CONFIG || ''], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+
+      serviceProcess.on('spawn', () => {
+        logger.info(\`Service process started with PID: \${serviceProcess?.pid}\`)
+        resolve()
+      })
+
+      serviceProcess.on('error', (error) => {
+        logger.error(\`Failed to start service process: \${error.message}\`)
+        reject(error)
+      })
+
+      serviceProcess.stdout?.on('data', (data) => {
+        logger.info(\`[SERVICE] \${data.toString().trim()}\`)
+      })
+
+      serviceProcess.stderr?.on('data', (data) => {
+        logger.error(\`[SERVICE ERROR] \${data.toString().trim()}\`)
+      })
+
+      serviceProcess.unref()
+    })
+  },
+
+  health: async ({ logger, utils }: HookContext) => {
+    logger.debug('Checking service health')
+    
+    if (!serviceProcess || !serviceProcess.pid) {
+      return false
+    }
+
+    try {
+      process.kill(serviceProcess.pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  },
+
+  stop: async ({ logger, utils }: HookContext) => {
+    logger.info('Stopping service process')
+    
+    if (serviceProcess && serviceProcess.pid) {
+      try {
+        process.kill(serviceProcess.pid, 'SIGTERM')
+        await utils.sleep(2000)
+        
+        try {
+          process.kill(serviceProcess.pid, 0)
+          process.kill(serviceProcess.pid, 'SIGKILL')
+          logger.warn('Had to force kill service process')
+        } catch {
+          logger.info('Service process stopped gracefully')
+        }
+      } catch (error) {
+        logger.debug('Service process already stopped')
+      }
+    }
+    
+    serviceProcess = null
+  }
+}
+`}getHooksWithMetrics(){return`import type { HookContext } from '@deeep-network/riptide'
+
+let requestCount = 0
+let errorCount = 0
+let serviceStartTime = Date.now()
+
+module.exports = {
+  installSecrets: async ({ logger }: HookContext) => {
+    logger.info('Installing secrets')
+    return { success: true }
+  },
+
+  start: async ({ logger }: HookContext) => {
+    logger.info('Service starting')
+    serviceStartTime = Date.now()
+    
+    setInterval(() => {
+      requestCount += Math.floor(Math.random() * 10)
+      if (Math.random() < 0.1) errorCount++
+    }, 5000)
+  },
+
+  health: async ({ logger }: HookContext) => {
+    logger.debug('Health check')
+    return true
+  },
+
+  heartbeat: async () => {
+    return {
+      service: 'your-service',
+      status: 'healthy',
+      uptime_seconds: Math.floor((Date.now() - serviceStartTime) / 1000),
+      request_count: requestCount,
+      error_count: errorCount
+    }
+  },
+
+  metrics: async () => {
+    const uptime = Math.floor((Date.now() - serviceStartTime) / 1000)
+    
+    let output = ''
+    output += '# HELP service_uptime_seconds Time since service started\\n'
+    output += '# TYPE service_uptime_seconds gauge\\n'
+    output += \`service_uptime_seconds \${uptime}\\n\\n\`
+    
+    output += '# HELP service_requests_total Total requests processed\\n'
+    output += '# TYPE service_requests_total counter\\n'
+    output += \`service_requests_total \${requestCount}\\n\\n\`
+    
+    output += '# HELP service_errors_total Total errors encountered\\n'
+    output += '# TYPE service_errors_total counter\\n'
+    output += \`service_errors_total \${errorCount}\\n\`
+    
+    return output
+  },
+
+  stop: async ({ logger }: HookContext) => {
+    logger.info('Service stopping')
+  }
+}
+`}async createDockerfile(e,t){let o=`# ${t} Service
+
+# ----------------------------------------
+# Base 
+# ----------------------------------------
+FROM node:22-alpine AS base
+RUN apk add --no-cache libc6-compat
+RUN npm install -g pnpm@10.8.0 turbo@2.5.0
+
+# ----------------------------------------
+# Turbo Pruner
+# ----------------------------------------
+FROM base AS pruner
+WORKDIR /app
+COPY . .
+RUN turbo prune reef-${t} --docker
+
+# ----------------------------------------
+# Turbo Builder and Pnpm Deployment
+# ----------------------------------------
+FROM base AS builder
+WORKDIR /app
+COPY --from=pruner /app/out/full/ .
+RUN pnpm install 
+COPY turbo.json tsconfig.json .
+RUN pnpm turbo run build --filter=reef-${t}... 
+
+# Create pnpm deployment
+RUN pnpm deploy --prod --filter reef-${t} deploy
+
+# ----------------------------------------
+# Minimal Runner
+# ----------------------------------------
+FROM node:22-alpine AS runner
+
+# Create application user
+RUN addgroup -g 1001 app && \\
+    adduser -u 1001 -G app -D app
+
+WORKDIR /app
+
+# Copy deployment artifacts
+COPY --from=builder --chown=app:app /app/deploy/dist ./dist
+COPY --from=builder --chown=app:app /app/deploy/node_modules ./node_modules
+COPY --from=builder --chown=app:app /app/deploy/package.json ./package.json
+COPY --from=builder --chown=app:app /app/deploy/riptide.config.json ./riptide.config.json
+
+# Create necessary directories
+RUN mkdir -p logs data tmp && chown -R app:app logs data tmp
+
+# Switch to non-root user
+USER app
+
+# Set environment
+ENV NODE_ENV=production
+
+# Start command
+CMD ["npm", "start"]
+`;await d.writeFile(u.join(e,"Dockerfile"),o)}showNextSteps(e,t){console.log(`
+Next steps:
+-----------
+1. Navigate to your service:
+   cd ${t}
+
+2. Install dependencies:
+   pnpm install
+
+3. Build the service:
+   pnpm run build
+
+4. Validate the hooks:
+   pnpm run validate
+
+5. Build Docker image:
+   pnpm run build:docker
+
+6. Run locally:
+   docker run -e API_KEY=your-key reef-${e}
+
+7. Add to turbo.json if needed for monorepo builds
+
+8. Customize the hooks in src/hooks.ts for your specific requirements
+`)}};async function z(r,e,t={}){await new w(r).scaffold({serviceName:e,...t})}n(z,"initService");0&&(module.exports={AlreadyRunningError,DiagnoseRequiredError,InvalidSecretError,MissingSecretError,RiptideEntrypoint,RiptideError,ServiceScaffolder,createChildLogger,createLogger,createUtilityContext,expandEnvironmentVariables,getDefaultConfig,initService,isAlreadyRunningError,isDiagnoseRequiredError,isInvalidSecretError,isMissingSecretError,isRiptideError,loadConfig,loadHooks,mergeConfigs,parseEnvironmentVariables,redactSecret,validateConfig});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deeep-network/riptide",
+  "version": "0.1.1",
+  "description": "Self-contained container orchestration library with lifecycle hooks",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "riptide": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsup",
+    "build:publish": "tsc --noEmit && tsup --minify",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build:publish"
+  },
+  "dependencies": {
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@types/node": "^22.14.0",
+    "tsup": "^8.5.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeep-network/riptide.git"
+  },
+  "keywords": [
+    "container",
+    "entrypoint",
+    "lifecycle",
+    "hooks",
+    "coral-reef",
+    "riptide"
+  ],
+  "author": "DEEEP Network",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}