@jondotsoy/pika 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Delgado hi@jon.soy https://jon.soy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @jondotsoy/pika
+
+A job execution framework with event-driven context management. Register and run named jobs with typed inputs, persistent YAML state, and automatic retries.
+
+## Install
+
+```bash
+npm install @jondotsoy/pika
+```
+
+## Usage
+
+Run your script directly with `npx`:
+
+```bash
+npx @jondotsoy/pika script.js
+```
+
+Or use the loader manually:
+
+```bash
+node --import @jondotsoy/pika/loader script.js
+```
+
+Define and execute jobs using the `app()` function:
+
+```javascript
+import { app } from "@jondotsoy/pika";
+
+const greet = app("greet", {
+  input: { name: z.string() },
+  handler: async ({ name }) => {
+    console.log(`Hello, ${name}!`);
+  },
+});
+
+greet("job-1", { name: "World" });
+```
+
+## Features
+
+- **Persistent state** — job state is automatically saved to a YAML manifest and survives process restarts
+- **Typed inputs** — input definitions provide TypeScript inference for job parameters
+- **Automatic retries** — jobs retry on failure up to `maxRetries` (default: 3)
+- **Parent-child jobs** — async local storage tracks job context across async boundaries
+- **Event-driven** — subscribe to lifecycle events or consume them as an async iterable
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/lib/esm/auth/dto/connection.d.ts

@@ -0,0 +1,43 @@
+export declare enum TypeConnection {
+    api_key = "API key",
+    basic_auth = "Basic auth",
+    oauth_2_0 = "OAuth 2.0"
+}
+export declare enum Placement {
+    headers = "headers",
+    query = "query"
+}
+export type APIKEYConnection = {
+    type: TypeConnection.api_key;
+    key: string;
+    placement?: Placement;
+    parameterName?: string;
+    prefix?: string;
+    sufix?: string;
+};
+export type BasicAuthConnection = {
+    type: TypeConnection.basic_auth;
+    username: string;
+    password: string;
+};
+export declare enum OAuth2_0FlowType {
+    code = "code",
+    implicit = "implicit"
+}
+export type OAuth2_0Connection = {
+    type: TypeConnection.oauth_2_0;
+    flowType: OAuth2_0FlowType;
+    authorizeURI: string;
+    tokenURI: string;
+    scope: string[];
+    clientID: string;
+    clientSecret: string;
+    authorizeParameters?: Record<string, string>;
+    accessTokenParameters?: Record<string, string>;
+    refreshTokenParameters?: Record<string, string>;
+    customHeaders?: Record<string, string>;
+    placement: Placement;
+    tokenPrefix?: string;
+    tokenSufix?: string;
+};
+export type Connection = APIKEYConnection | BasicAuthConnection | OAuth2_0Connection;

package/lib/esm/auth/dto/connection.js

@@ -0,0 +1,16 @@
+export var TypeConnection;
+(function (TypeConnection) {
+    TypeConnection["api_key"] = "API key";
+    TypeConnection["basic_auth"] = "Basic auth";
+    TypeConnection["oauth_2_0"] = "OAuth 2.0";
+})(TypeConnection || (TypeConnection = {}));
+export var Placement;
+(function (Placement) {
+    Placement["headers"] = "headers";
+    Placement["query"] = "query";
+})(Placement || (Placement = {}));
+export var OAuth2_0FlowType;
+(function (OAuth2_0FlowType) {
+    OAuth2_0FlowType["code"] = "code";
+    OAuth2_0FlowType["implicit"] = "implicit";
+})(OAuth2_0FlowType || (OAuth2_0FlowType = {}));

package/lib/esm/auth/index.d.ts

@@ -0,0 +1,10 @@
+import { TypeConnection, Placement } from "./dto/connection.js";
+export { TypeConnection, Placement, OAuth2_0FlowType, } from "./dto/connection.js";
+export type { Connection, APIKEYConnection, BasicAuthConnection, OAuth2_0Connection, } from "./dto/connection.js";
+export type Credentials = {
+    type: TypeConnection;
+    placement?: Placement;
+    parameterName?: string;
+    value(): Promise<string>;
+};
+export declare function getCredentials(name: string): Promise<Credentials>;

package/lib/esm/auth/index.js

@@ -0,0 +1,64 @@
+import { TypeConnection, } from "./dto/connection.js";
+export { TypeConnection, Placement, OAuth2_0FlowType, } from "./dto/connection.js";
+function toCredentials(conn) {
+    if (conn.type === TypeConnection.api_key) {
+        return {
+            type: conn.type,
+            placement: conn.placement,
+            parameterName: conn.parameterName,
+            value: async () => `${conn.prefix ?? ""}${conn.key}${conn.sufix ?? ""}`,
+        };
+    }
+    if (conn.type === TypeConnection.basic_auth) {
+        return {
+            type: conn.type,
+            value: async () => `Basic ${btoa(`${conn.username}:${conn.password}`)}`,
+        };
+    }
+    // oauth_2_0
+    return {
+        type: conn.type,
+        placement: conn.placement,
+        value: async () => {
+            const body = new URLSearchParams({
+                grant_type: "client_credentials",
+                client_id: conn.clientID,
+                client_secret: conn.clientSecret,
+                scope: conn.scope.join(" "),
+                ...conn.accessTokenParameters,
+            });
+            const headers = {
+                "Content-Type": "application/x-www-form-urlencoded",
+                ...conn.customHeaders,
+            };
+            const res = await fetch(conn.tokenURI, { method: "POST", headers, body });
+            const data = await res.json();
+            const prefix = conn.tokenPrefix ?? "Bearer ";
+            const sufix = conn.tokenSufix ?? "";
+            // @ts-ignore
+            return `${prefix}${data.access_token}${sufix}`;
+        },
+    };
+}
+async function decryptCredentials(encrypted, publicKey) {
+    const keyBytes = Buffer.from(publicKey, "base64");
+    const encryptedBytes = Buffer.from(encrypted, "base64");
+    const iv = encryptedBytes.subarray(0, 12);
+    const ciphertext = encryptedBytes.subarray(12);
+    const cryptoKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["decrypt"]);
+    const decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, cryptoKey, ciphertext);
+    return new TextDecoder().decode(decrypted);
+}
+export async function getCredentials(name) {
+    const raw = process.env.PIKA_CONTEXT_CREDENTIALS;
+    if (!raw)
+        throw new Error("PIKA_CONTEXT_CREDENTIALS is not set");
+    const publicKey = process.env.PIKA_CONTEXT_CREDENTIALS_PUBLIC_KEY;
+    const json = publicKey ? await decryptCredentials(raw, publicKey) : raw;
+    const store = JSON.parse(json);
+    const conn = store[name];
+    if (!conn)
+        throw new Error(`Connection "${name}" not found`);
+    // @ts-ignore
+    return toCredentials(conn);
+}

package/lib/esm/cli/__samples__/parent-child-script.d.ts

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

package/lib/esm/cli/__samples__/parent-child-script.js

@@ -0,0 +1,9 @@
+import { app } from "@jondotsoy/pika";
+const child = app("child-job", {}, async () => {
+    await new Promise((r) => setTimeout(r, 20));
+});
+const parent = app("parent-job", {}, async () => {
+    child("child-1", {});
+    child("child-2", {});
+});
+parent("run-1", {});

package/lib/esm/cli/cli-event-payload.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const CliEventPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodLiteral<"job_created">;
+    jobId: z.ZodString;
+    job: z.ZodObject<{
+        appId: z.ZodString;
+        parentJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"job_started">;
+    jobId: z.ZodString;
+    job: z.ZodObject<{
+        appId: z.ZodString;
+        parentJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"job_done">;
+    jobId: z.ZodString;
+    job: z.ZodObject<{
+        appId: z.ZodString;
+        parentJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"job_error">;
+    jobId: z.ZodString;
+    job: z.ZodObject<{
+        appId: z.ZodString;
+        parentJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    error: z.ZodObject<{
+        name: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"job_retry">;
+    jobId: z.ZodString;
+    job: z.ZodObject<{
+        appId: z.ZodString;
+        parentJobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    retryCount: z.ZodNumber;
+}, z.core.$strip>], "event">;
+export type CliEventPayload = z.infer<typeof CliEventPayloadSchema>;

package/lib/esm/cli/cli-event-payload.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+const JobSchema = z.object({
+    appId: z.string(),
+    parentJobId: z.string().nullable().optional(),
+    startedAt: z.string().nullable().optional(),
+    completedAt: z.string().nullable().optional(),
+});
+export const CliEventPayloadSchema = z.discriminatedUnion("event", [
+    z.object({
+        event: z.literal("job_created"),
+        jobId: z.string(),
+        job: JobSchema,
+    }),
+    z.object({
+        event: z.literal("job_started"),
+        jobId: z.string(),
+        job: JobSchema,
+    }),
+    z.object({ event: z.literal("job_done"), jobId: z.string(), job: JobSchema }),
+    z.object({
+        event: z.literal("job_error"),
+        jobId: z.string(),
+        job: JobSchema,
+        error: z.object({ name: z.string(), message: z.string() }),
+    }),
+    z.object({
+        event: z.literal("job_retry"),
+        jobId: z.string(),
+        job: JobSchema,
+        retryCount: z.number(),
+    }),
+]);

package/lib/esm/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/esm/cli/index.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { serve } from "./utils/create-server.js";
+import { CliEventPayloadSchema, } from "./cli-event-payload.js";
+import { flags, argument } from "@jondotsoy/flags";
+var Engine;
+(function (Engine) {
+    Engine[Engine["BUN"] = 0] = "BUN";
+    Engine[Engine["NODE"] = 1] = "NODE";
+    // DENO
+})(Engine || (Engine = {}));
+function detectEngine() {
+    const ARG0 = process.argv0.toLowerCase();
+    const enginesMatch = [
+        [Engine.BUN, ARG0.endsWith("bun") || ARG0.endsWith("bunx")],
+        [Engine.NODE, ARG0.endsWith("node") || ARG0.endsWith("node.exe")],
+        // [Engine.DENO, ARG0.endsWith("deno") || ARG0.endsWith("deno.exe")]
+    ];
+    const engine = enginesMatch.find(([_, match]) => match)?.[0] ?? null;
+    if (engine === null) {
+        throw new Error(`Unsupported JavaScript engine: ${ARG0}`);
+    }
+    return { argv0: process.argv0, engine };
+}
+const parser = flags({
+    script: argument().string().describe("Script to run"),
+}).program("pika");
+function parseArgs() {
+    const [ok, error, output] = parser.safeParse(process.argv.slice(2));
+    if (!ok) {
+        console.error(parser.formatError(error));
+        process.exit(1);
+    }
+    const script = output.script;
+    if (!script) {
+        console.error("No script provided. Usage: pika <script>");
+        process.exit(1);
+    }
+    return { script };
+}
+const jobs = new Map();
+function applyEvent(payload) {
+    const { jobId, job } = payload;
+    const existing = jobs.get(jobId);
+    let status = existing?.status ?? "running";
+    if (payload.event === "job_done")
+        status = "done";
+    else if (payload.event === "job_error")
+        status = "error";
+    else if (payload.event === "job_started" ||
+        payload.event === "job_created" ||
+        payload.event === "job_retry")
+        status = "running";
+    jobs.set(jobId, {
+        jobId,
+        parentJobId: job.parentJobId ?? null,
+        appId: job.appId,
+        status,
+        startedAt: job.startedAt ? new Date(job.startedAt) : null,
+        completedAt: job.completedAt ? new Date(job.completedAt) : null,
+    });
+}
+// --- Terminal renderer ---
+const isTTY = process.stdout.isTTY === true;
+let prevLineCount = 0;
+function renderJobs() {
+    const now = Date.now();
+    const lines = [];
+    // Group children by parentJobId
+    const childrenOf = new Map();
+    const roots = [];
+    for (const entry of jobs.values()) {
+        if (entry.parentJobId === null) {
+            roots.push(entry);
+        }
+        else {
+            const siblings = childrenOf.get(entry.parentJobId) ?? [];
+            siblings.push(entry);
+            childrenOf.set(entry.parentJobId, siblings);
+        }
+    }
+    function formatEntry(entry, indent) {
+        const prefix = "    ".repeat(indent);
+        const { jobId, status, startedAt, completedAt } = entry;
+        let durationSec = 0;
+        if (startedAt) {
+            const endMs = completedAt ? completedAt.getTime() : now;
+            durationSec = Math.round((endMs - startedAt.getTime()) / 1000);
+        }
+        lines.push(`${prefix}${jobId}: ${status} ${durationSec}s`);
+        const children = childrenOf.get(jobId) ?? [];
+        for (const child of children) {
+            formatEntry(child, indent + 1);
+        }
+    }
+    for (const root of roots) {
+        formatEntry(root, 0);
+    }
+    // Erase previous render then write new
+    if (prevLineCount > 0) {
+        process.stdout.write(`\x1B[${prevLineCount}A\x1B[0J`);
+    }
+    if (lines.length > 0) {
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+    prevLineCount = lines.length;
+}
+// --- Inspector HTTP server ---
+async function startInspector(onEvent) {
+    const key = crypto.randomUUID();
+    const server = await serve({
+        port: 0,
+        routes: {
+            [`/inspector/${key}`]: {
+                POST: async (request) => {
+                    try {
+                        onEvent(CliEventPayloadSchema.parse(await request.json()));
+                    }
+                    catch { }
+                    return new Response(null, { status: 204 });
+                },
+            },
+        },
+    });
+    const inspectorUrl = `${server.url}inspector/${key}`;
+    return { inspectorUrl, stop: server.close };
+}
+// --- Main ---
+async function main() {
+    const { argv0, engine } = detectEngine();
+    const { script } = parseArgs();
+    const { inspectorUrl, stop } = await startInspector((payload) => {
+        applyEvent(payload);
+        if (isTTY) {
+            try {
+                renderJobs();
+            }
+            catch {
+                // Non-TTY or unsupported terminal — skip rendering
+            }
+        }
+    });
+    const args = {
+        [Engine.BUN]: ["run", "--import", "@jondotsoy/pika/loader", script],
+        [Engine.NODE]: ["--import", "@jondotsoy/pika/loader", script],
+    };
+    const child = spawn(argv0, args[engine], {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            PIKA_CLI_INSPECTOR_URL: inspectorUrl,
+        },
+    });
+    await new Promise((resolve) => {
+        child.on("exit", (code) => {
+            stop();
+            if (code !== null && code !== 0) {
+                process.exitCode = code;
+            }
+            resolve();
+        });
+    });
+}
+main().catch((error) => {
+    console.error("Error:", error);
+    process.exit(1);
+});

package/lib/esm/cli/utils/create-server.d.ts

@@ -0,0 +1,20 @@
+type RouteHandler = (request: Request) => Response | Promise<Response>;
+type RouteMethod = {
+    GET?: RouteHandler;
+    POST?: RouteHandler;
+    PUT?: RouteHandler;
+    PATCH?: RouteHandler;
+    DELETE?: RouteHandler;
+};
+type Routes = Record<string, RouteMethod>;
+type ServeOptions = {
+    port?: number;
+    hostname?: string;
+    routes: Routes;
+};
+type Server = {
+    url: URL;
+    close: () => void;
+};
+export declare function serve(options: ServeOptions): Promise<Server>;
+export {};

package/lib/esm/cli/utils/create-server.js

@@ -0,0 +1,70 @@
+import { createServer, } from "node:http";
+async function toNodeResponse(res, webResponse) {
+    const headers = {};
+    webResponse.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    res.writeHead(webResponse.status, headers);
+    const body = await webResponse.arrayBuffer();
+    res.end(Buffer.from(body));
+}
+async function toWebRequest(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const body = chunks.length > 0 ? Buffer.concat(chunks) : null;
+    const url = `http://localhost${req.url ?? "/"}`;
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value !== undefined) {
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    headers.append(key, v);
+            }
+            else {
+                headers.set(key, value);
+            }
+        }
+    }
+    return new Request(url, {
+        method: req.method ?? "GET",
+        headers,
+        body: body && body.length > 0 ? body : null,
+    });
+}
+export function serve(options) {
+    const { port = 0, hostname = "localhost", routes } = options;
+    return new Promise((resolve, reject) => {
+        const server = createServer(async (req, res) => {
+            const path = req.url?.split("?")[0] ?? "/";
+            const method = req.method ?? "GET";
+            const routeMethods = routes[path];
+            const handler = routeMethods?.[method];
+            if (!handler) {
+                res.writeHead(404).end();
+                return;
+            }
+            try {
+                const webRequest = await toWebRequest(req);
+                const webResponse = await handler(webRequest);
+                await toNodeResponse(res, webResponse);
+            }
+            catch {
+                res.writeHead(500).end();
+            }
+        });
+        server.listen(port, hostname, () => {
+            const addr = server.address();
+            const host = addr.address.includes(":")
+                ? `[${addr.address}]`
+                : addr.address;
+            const url = new URL(`http://${host}:${addr.port}`);
+            resolve({
+                url,
+                close: () => server.close(),
+            });
+        });
+        server.on("error", reject);
+    });
+}

package/lib/esm/flow/__samples__/credentials-job.d.ts

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

package/lib/esm/flow/__samples__/credentials-job.js

@@ -0,0 +1,9 @@
+import { app } from "../index.js";
+import { http } from "../../http/index.js";
+import { getCredentials } from "../../auth/index.js";
+const job = app("credentials-job", {}, async () => {
+    const credentials = await getCredentials("mykey");
+    const { body } = await http(process.env.MOCK_SERVER_URL, { credentials });
+    console.log(`job completed authorized=${body.authorized}`);
+});
+job("run-1", {});

package/lib/esm/flow/__samples__/only-app.d.ts

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

package/lib/esm/flow/__samples__/only-app.js

@@ -0,0 +1,4 @@
+import { app } from "../index.js";
+app("wait-job", {}, async () => {
+    console.log("job completed");
+});

package/lib/esm/flow/__samples__/parent-child-jobs.d.ts

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

package/lib/esm/flow/__samples__/parent-child-jobs.js

@@ -0,0 +1,10 @@
+import { app } from "../index.js";
+const childJob = app("child-app", {}, async () => {
+    console.log("child job done");
+});
+const mainJob = app("main-app", {}, async () => {
+    console.log("main job running");
+    childJob("child-1", {});
+    childJob("child-2", {});
+});
+mainJob("main-run", {});

package/lib/esm/flow/__samples__/parent-with-subjobs.d.ts

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

package/lib/esm/flow/__samples__/parent-with-subjobs.js

@@ -0,0 +1,9 @@
+import { app } from "../index.js";
+const subJob = app("sub-job", {}, async () => {
+    console.log("subjob completed");
+});
+const parentJob = app("parent-job", {}, async () => {
+    subJob("sub-1", {});
+    subJob("sub-2", {});
+});
+parentJob("parent-run", {});

package/lib/esm/flow/__samples__/wait-job.d.ts

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

package/lib/esm/flow/__samples__/wait-job.js

@@ -0,0 +1,6 @@
+import { app } from "../index.js";
+const job = app("wait-job", {}, async () => {
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    console.log("job completed");
+});
+job("run-1", {});

package/lib/esm/flow/__samples__/zod-invalid-job.d.ts

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

package/lib/esm/flow/__samples__/zod-invalid-job.js

@@ -0,0 +1,4 @@
+import { app } from "../index.js";
+import { z } from "zod";
+const job = app("zod-invalid-job", { name: z.string(), age: z.number() }, async () => { });
+job("run-1", { name: "Bob", age: "not-a-number" });

package/lib/esm/flow/__samples__/zod-validation-job.d.ts

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

package/lib/esm/flow/__samples__/zod-validation-job.js

@@ -0,0 +1,6 @@
+import { app } from "../index.js";
+import { z } from "zod";
+const job = app("zod-validation-job", { name: z.string().min(1), age: z.number().int().positive() }, async (params) => {
+    console.log(`job completed name=${params.name} age=${params.age}`);
+});
+job("run-1", { name: "Alice", age: 30 });