@hitch42/applet 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hitch42 Pty Ltd
+
+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/dist/_internal/client.d.ts

@@ -0,0 +1,7 @@
+import { PersistQueryClientOptions } from "@tanstack/react-query-persist-client";
+import { AnyRouter } from "@tanstack/react-router";
+//#region src/internal/client.d.ts
+declare function appletQueryPersistence(appletCode: string): Promise<Omit<PersistQueryClientOptions, "queryClient"> | undefined>;
+declare function mountApplet(router: AnyRouter, appletCode: string): void;
+//#endregion
+export { appletQueryPersistence, mountApplet };

package/dist/_internal/client.js

@@ -0,0 +1,60 @@
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { RouterProvider } from "@tanstack/react-router";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+//#region src/internal/client.ts
+const CACHE_MAX_AGE = 3e5;
+const CACHE_SCOPE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function appletQueryPersistence(appletCode) {
+	const contextPromise = window.__hitchCacheContext;
+	if (!contextPromise) return void 0;
+	let context;
+	try {
+		context = await contextPromise;
+	} catch (error) {
+		console.error("Could not load the applet cache context.", error);
+		return;
+	}
+	const cacheScope = typeof context === "object" && context !== null && "cacheScope" in context && typeof context.cacheScope === "string" ? context.cacheScope.trim() : void 0;
+	const cacheBuster = typeof context === "object" && context !== null && "cacheBuster" in context && typeof context.cacheBuster === "string" ? context.cacheBuster.trim() : void 0;
+	if (!cacheScope || !CACHE_SCOPE_PATTERN.test(cacheScope) || !cacheBuster || !CACHE_SCOPE_PATTERN.test(cacheBuster)) return;
+	try {
+		return {
+			persister: createAsyncStoragePersister({
+				storage: window.sessionStorage,
+				key: `hitch:query:${appletCode}:${cacheScope}`,
+				throttleTime: 100,
+				retry: ({ error }) => {
+					console.error("Could not persist the applet query cache.", error);
+				}
+			}),
+			maxAge: CACHE_MAX_AGE,
+			buster: cacheBuster,
+			dehydrateOptions: { shouldDehydrateMutation: () => false }
+		};
+	} catch (error) {
+		console.error("Could not access applet query cache storage.", error);
+		return;
+	}
+}
+function mountApplet(router, appletCode) {
+	const queryClient = router.options.context.queryClient;
+	if (!queryClient) throw new Error("getRouter must provide a QueryClient via createRouter({ context: { queryClient } }).");
+	const root = document.getElementById("root");
+	if (root === null) throw new Error("Missing #root element in index.html.");
+	const applet = createElement(RouterProvider, { router });
+	appletQueryPersistence(appletCode).then((persistence) => {
+		createRoot(root).render(persistence ? createElement(PersistQueryClientProvider, {
+			client: queryClient,
+			persistOptions: persistence,
+			onError: () => console.error("Could not restore the applet query cache.")
+		}, applet) : createElement(QueryClientProvider, { client: queryClient }, applet));
+	}).catch((error) => {
+		console.error("Could not initialize the applet query cache.", error);
+		createRoot(root).render(createElement(QueryClientProvider, { client: queryClient }, applet));
+	});
+}
+//#endregion
+export { appletQueryPersistence, mountApplet };

package/dist/_internal/server.d.ts

@@ -0,0 +1,79 @@
+import { t as AnyWorkflowDefinition } from "../workflow-DurM6Fwx.js";
+import { z } from "zod";
+//#region src/server/entry.d.ts
+declare function createWorkerEntry(server: {
+  router: object;
+  workflows?: Record<string, AnyWorkflowDefinition>;
+}, options: {
+  code: string;
+}): {
+  fetch(request: Request, env?: unknown, ctx?: unknown): Promise<Response>;
+};
+//#endregion
+//#region src/server/workflow-protocol.d.ts
+type StepJournalEntry = {
+  kind: "step";
+  id: string;
+  name: string;
+  result: unknown;
+};
+type SleepJournalEntry = {
+  kind: "sleep";
+  id: string;
+  name: string;
+  until: number;
+};
+type AttemptJournalEntry = {
+  kind: "attempt";
+  id: string;
+  name: string;
+  error: string;
+};
+type FailedJournalEntry = {
+  kind: "failed";
+  id: string;
+  name: string;
+  error: string;
+};
+declare const journalEntrySchema: z.ZodType<StepJournalEntry | SleepJournalEntry | AttemptJournalEntry | FailedJournalEntry>;
+type JournalEntry = z.infer<typeof journalEntrySchema>;
+declare const workflowInvocationRequestSchema: z.ZodType<{
+  payload: unknown;
+  journal: JournalEntry[];
+}>;
+type WorkflowInvocationRequest = z.infer<typeof workflowInvocationRequestSchema>;
+type StepOutcome = {
+  kind: "step";
+  id: string;
+  name: string;
+  result: unknown;
+};
+type SleepOutcome = {
+  kind: "sleep";
+  id: string;
+  name: string;
+  until: number;
+};
+type StepErrorOutcome = {
+  kind: "step_error";
+  id: string;
+  name: string;
+  message: string;
+  retries: {
+    limit: number;
+    delayMs: number;
+    backoff: "constant" | "linear" | "exponential";
+  };
+};
+type DoneOutcome = {
+  kind: "done";
+  result: unknown;
+};
+type ErrorOutcome = {
+  kind: "error";
+  message: string;
+};
+declare const workflowOutcomeSchema: z.ZodType<StepOutcome | SleepOutcome | StepErrorOutcome | DoneOutcome | ErrorOutcome>;
+type WorkflowOutcome = z.infer<typeof workflowOutcomeSchema>;
+//#endregion
+export { type JournalEntry, type WorkflowInvocationRequest, type WorkflowOutcome, createWorkerEntry, journalEntrySchema, workflowInvocationRequestSchema, workflowOutcomeSchema };

package/dist/_internal/server.js

@@ -0,0 +1,232 @@
+import { o as runWithRequestContext, r as toMilliseconds, t as MAX_DURATION_MS } from "../workflow-CTo2kZF1.js";
+import { z } from "zod";
+import { RPCHandler } from "@orpc/server/fetch";
+//#region src/headers.ts
+const HITCH_USER_HEADER = "x-hitch-user";
+const HITCH_SESSION_HEADER = "x-hitch-session";
+const HITCH_APPLET_HEADER = "x-hitch-applet";
+const HITCH_APPLET_TOKEN_HEADER = "x-hitch-applet-token";
+//#endregion
+//#region src/server/workflow-protocol.ts
+const journalEntrySchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("step"),
+		id: z.string(),
+		name: z.string(),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("sleep"),
+		id: z.string(),
+		name: z.string(),
+		until: z.number()
+	}),
+	z.object({
+		kind: z.literal("attempt"),
+		id: z.string(),
+		name: z.string(),
+		error: z.string()
+	}),
+	z.object({
+		kind: z.literal("failed"),
+		id: z.string(),
+		name: z.string(),
+		error: z.string()
+	})
+]);
+const workflowInvocationRequestSchema = z.object({
+	payload: z.unknown(),
+	journal: z.array(journalEntrySchema)
+});
+const workflowOutcomeSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("step"),
+		id: z.string(),
+		name: z.string(),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("sleep"),
+		id: z.string(),
+		name: z.string(),
+		until: z.number()
+	}),
+	z.object({
+		kind: z.literal("step_error"),
+		id: z.string(),
+		name: z.string(),
+		message: z.string(),
+		retries: z.object({
+			limit: z.number(),
+			delayMs: z.number(),
+			backoff: z.enum([
+				"constant",
+				"linear",
+				"exponential"
+			])
+		})
+	}),
+	z.object({
+		kind: z.literal("done"),
+		result: z.unknown()
+	}),
+	z.object({
+		kind: z.literal("error"),
+		message: z.string()
+	})
+]);
+//#endregion
+//#region src/server/workflow-run.ts
+const MAX_RESULT_SIZE = 1048576;
+function errorMessage(error) {
+	return (error instanceof Error ? error.message : String(error)).slice(0, 2048);
+}
+function outcomeTooLarge(outcome) {
+	return new TextEncoder().encode(JSON.stringify(outcome)).byteLength > MAX_RESULT_SIZE;
+}
+async function runWorkflowInvocation(definition, request) {
+	const occurrences = /* @__PURE__ */ new Map();
+	const never = new Promise(() => void 0);
+	let claimed = false;
+	let resolveRecorded = () => void 0;
+	const recordedPromise = new Promise((resolve) => {
+		resolveRecorded = resolve;
+	});
+	const nextId = (name) => {
+		const occurrence = (occurrences.get(name) ?? 0) + 1;
+		occurrences.set(name, occurrence);
+		return `${name}#${occurrence}`;
+	};
+	const record = (outcome) => {
+		resolveRecorded(outcome);
+		return never;
+	};
+	const runPromise = definition.run({
+		async do(name, optionsOrFn, possibleFn) {
+			const id = nextId(name);
+			const journaled = request.journal.find((entry) => entry.kind === "step" && entry.id === id);
+			if (journaled?.kind === "step") return journaled.result;
+			const failed = request.journal.find((entry) => entry.kind === "failed" && entry.id === id);
+			if (failed?.kind === "failed") throw new Error(failed.error);
+			if (claimed) return never;
+			claimed = true;
+			const options = typeof optionsOrFn === "function" ? void 0 : optionsOrFn;
+			const fn = typeof optionsOrFn === "function" ? optionsOrFn : possibleFn;
+			const retries = options?.retries ? {
+				limit: options.retries.limit,
+				delayMs: toMilliseconds(options.retries.delay),
+				backoff: options.retries.backoff ?? "constant"
+			} : {
+				limit: 0,
+				delayMs: 0,
+				backoff: "constant"
+			};
+			if (retries.delayMs * (retries.backoff === "exponential" ? 2 ** (retries.limit - 1) : retries.backoff === "linear" ? retries.limit : 1) > MAX_DURATION_MS) throw new Error("Retry delay grows beyond 365 days.");
+			try {
+				const outcome = {
+					kind: "step",
+					id,
+					name,
+					result: await fn()
+				};
+				return record(outcomeTooLarge(outcome) ? {
+					kind: "error",
+					message: `Step "${name}" result exceeds 1 MiB.`
+				} : outcome);
+			} catch (error) {
+				return record({
+					kind: "step_error",
+					id,
+					name,
+					message: errorMessage(error),
+					retries
+				});
+			}
+		},
+		async sleep(name, duration) {
+			const id = nextId(name);
+			if (request.journal.find((entry) => entry.kind === "sleep" && entry.id === id) !== void 0) return;
+			if (claimed) return never;
+			claimed = true;
+			return record({
+				kind: "sleep",
+				id,
+				name,
+				until: Date.now() + toMilliseconds(duration)
+			});
+		}
+	}, request.payload).then((result) => {
+		const outcome = {
+			kind: "done",
+			result
+		};
+		return outcomeTooLarge(outcome) ? {
+			kind: "error",
+			message: "Workflow result exceeds 1 MiB."
+		} : outcome;
+	}, (error) => ({
+		kind: "error",
+		message: errorMessage(error)
+	}));
+	return Promise.race([runPromise, recordedPromise]);
+}
+//#endregion
+//#region src/server/entry.ts
+const WORKFLOW_PATH_PREFIX = "/api/__hitch/workflows/";
+const SERVER_EXPORT_ERROR = "src/server/main.ts must default-export { router, workflows } — change \"export default router\" to \"export default { router }\".";
+function jsonError(status, error) {
+	return Response.json({ error }, { status });
+}
+function createWorkerEntry(server, options) {
+	const candidate = server;
+	if (typeof candidate !== "object" || candidate === null || !("router" in candidate)) throw new Error(SERVER_EXPORT_ERROR);
+	const handler = new RPCHandler(server.router);
+	return { async fetch(request, env) {
+		const userId = request.headers.get(HITCH_USER_HEADER);
+		const sessionToken = request.headers.get(HITCH_SESSION_HEADER);
+		const appletId = request.headers.get(HITCH_APPLET_HEADER);
+		const token = request.headers.get(HITCH_APPLET_TOKEN_HEADER);
+		const identity = userId !== null && sessionToken !== null ? {
+			kind: "user",
+			userId,
+			sessionToken
+		} : appletId !== null && token !== null ? {
+			kind: "applet",
+			appletId,
+			token
+		} : void 0;
+		if (identity === void 0) return jsonError(401, "missing_identity");
+		const bindings = typeof env === "object" && env !== null ? env : {};
+		if (typeof bindings.HITCH_API_URL !== "string") return jsonError(500, "missing_api_binding");
+		const service = typeof bindings.HITCH === "object" && bindings.HITCH !== null ? bindings.HITCH : void 0;
+		const apiFetch = typeof service?.fetch === "function" ? service.fetch.bind(bindings.HITCH) : globalThis.fetch.bind(globalThis);
+		return runWithRequestContext({
+			identity,
+			appletCode: options.code,
+			api: {
+				baseUrl: bindings.HITCH_API_URL,
+				fetch: apiFetch
+			}
+		}, async () => {
+			const pathname = new URL(request.url).pathname;
+			if (pathname.startsWith(WORKFLOW_PATH_PREFIX)) {
+				const parsed = await request.json().then((body) => workflowInvocationRequestSchema.safeParse(body)).catch(() => void 0);
+				if (parsed === void 0 || !parsed.success) return jsonError(400, "malformed_request");
+				const code = decodeURIComponent(pathname.slice(23));
+				const workflows = server.workflows ?? {};
+				const definition = Object.hasOwn(workflows, code) ? workflows[code] : void 0;
+				return Response.json(definition === void 0 ? {
+					kind: "error",
+					message: `Unknown workflow "${code}".`
+				} : await runWorkflowInvocation(definition, parsed.data));
+			}
+			const result = await handler.handle(request, {
+				context: {},
+				prefix: "/api"
+			});
+			return result.matched ? result.response : new Response(null, { status: 404 });
+		});
+	} };
+}
+//#endregion
+export { createWorkerEntry, journalEntrySchema, workflowInvocationRequestSchema, workflowOutcomeSchema };

package/dist/applet.d.ts

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

package/dist/applet.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+//#region bin/applet.ts
+const usage = `Usage:
+  applet init <org> [--no-commit | --no-git] [--no-install]
+  applet bootstrap [--no-install]
+  applet new <code> [--client-only | --server-only] [--no-install]
+  applet generate [--changeset <id>]
+  applet build [--changeset <id>]
+  applet deploy [--changeset <id>]
+  applet logs [code] [--since <duration>] [--limit <count>]
+                     [--search <text>] [--level <level>] [--filter <json>] [--run <id>] [--live]
+  applet variables set <KEY> [value] [--secret] [-y | --yes]
+  applet variables list
+  applet variables delete <KEY> [-y | --yes]
+
+Init options:
+  --no-commit        Do not create the initial commit
+  --no-git           Do not create a git repository
+  --no-install       Do not run pnpm install
+
+New options:
+  --client-only      Create only client source
+  --server-only      Create only server source
+  --no-install       Do not run pnpm install
+
+Bootstrap options:
+  --no-install       Do not run pnpm install
+
+Generate options:
+  --changeset <id>    Generate against the schema this pending changeset
+                      would produce. The build honours HITCH_CHANGESET_ID.
+
+Deploy options:
+  --changeset <id>    Deploy against a pending schema changeset. The build
+                      generates against its schema and the release promotes
+                      when the changeset applies. Manifest mismatches warn.
+
+Logs options:
+  --since <duration>  Show logs from this period. Default: 1h. Maximum: 7d.
+  --limit <count>     Return up to this many logs. Default: 100. Maximum: 100.
+  --search <text>     Search log text.
+  --level <level>     Show this level and higher levels.
+                      Valid levels: debug, log, info, warn, error.
+                      The log level is an alias for info.
+  --run <id>          Show workflow logs for one run.
+  --filter <json>     Filter log fields with a Hitch JSON filter object.
+  --live              Poll for new logs every two seconds.
+
+Variables options:
+  --secret            Store the value as a secret.
+  -y, --yes           Skip the live applet confirmation.
+
+CI: set HITCH_API_KEY (and HITCH_API_URL for a non-default instance).`;
+async function main() {
+	const { positionals, values } = parseArgs({
+		allowPositionals: true,
+		options: {
+			changeset: { type: "string" },
+			"client-only": { type: "boolean" },
+			filter: { type: "string" },
+			run: { type: "string" },
+			level: { type: "string" },
+			limit: { type: "string" },
+			live: { type: "boolean" },
+			"no-commit": { type: "boolean" },
+			"no-git": { type: "boolean" },
+			"no-install": { type: "boolean" },
+			secret: { type: "boolean" },
+			search: { type: "string" },
+			"server-only": { type: "boolean" },
+			since: { type: "string" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			}
+		},
+		strict: true
+	});
+	const noGitFlags = values["no-commit"] === void 0 && values["no-git"] === void 0;
+	const noVariableFlags = values.secret === void 0 && values.yes === void 0;
+	const noLogFlags = values.run === void 0 && values.filter === void 0 && values.level === void 0 && values.limit === void 0 && values.live === void 0 && values.search === void 0 && values.since === void 0;
+	const noModeFlags = values["client-only"] === void 0 && values["server-only"] === void 0;
+	if (positionals.length === 1 && positionals[0] === "bootstrap" && values.changeset === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./init-BS1Y-eNL.js")).runBootstrap({ install: values["no-install"] !== true });
+		return;
+	}
+	if (positionals.length === 1 && positionals[0] === "generate" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./generate-6Nbt7uii.js")).runGenerate({ changesetId: values.changeset });
+		return;
+	}
+	if (positionals.length === 1 && positionals[0] === "build" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./build-CEku1lyb.js")).runBuild({ changesetId: values.changeset });
+		return;
+	}
+	if (positionals.length === 1 && positionals[0] === "deploy" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./deploy-D3BGDqgC.js")).runDeploy({ changesetId: values.changeset });
+		return;
+	}
+	if (positionals.length === 2 && positionals[0] === "init" && values.changeset === void 0 && noModeFlags && noVariableFlags && noLogFlags) {
+		await (await import("./init-BS1Y-eNL.js")).runInit(positionals[1], {
+			commit: values["no-commit"] !== true,
+			git: values["no-git"] !== true,
+			install: values["no-install"] !== true
+		});
+		return;
+	}
+	if (positionals.length === 2 && positionals[0] === "new" && values.changeset === void 0 && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./init-BS1Y-eNL.js")).runNew({
+			code: positionals[1],
+			clientOnly: values["client-only"],
+			install: values["no-install"] !== true,
+			serverOnly: values["server-only"]
+		});
+		return;
+	}
+	if ((positionals.length === 1 || positionals.length === 2) && positionals[0] === "logs" && values.changeset === void 0 && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags) {
+		await (await import("./logs-m00pzr_O.js")).runLogs({
+			code: positionals[1],
+			filter: values.filter,
+			run: values.run,
+			level: values.level,
+			limit: values.limit,
+			live: values.live,
+			search: values.search,
+			since: values.since
+		});
+		return;
+	}
+	if ((positionals.length === 3 || positionals.length === 4) && positionals[0] === "variables" && values.changeset === void 0 && positionals[1] === "set" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noLogFlags) {
+		await (await import("./variables-CP7Ce3Np.js")).runVariablesSet({
+			key: positionals[2],
+			secret: values.secret,
+			value: positionals[3],
+			yes: values.yes
+		});
+		return;
+	}
+	if (positionals.length === 2 && positionals[0] === "variables" && values.changeset === void 0 && positionals[1] === "list" && values["no-install"] === void 0 && noModeFlags && noGitFlags && noVariableFlags && noLogFlags) {
+		await (await import("./variables-CP7Ce3Np.js")).runVariablesList({});
+		return;
+	}
+	if (positionals.length === 3 && positionals[0] === "variables" && values.changeset === void 0 && positionals[1] === "delete" && values["no-install"] === void 0 && noModeFlags && noGitFlags && values.secret === void 0 && noLogFlags) {
+		await (await import("./variables-CP7Ce3Np.js")).runVariablesDelete({
+			key: positionals[2],
+			yes: values.yes
+		});
+		return;
+	}
+	throw new Error(usage);
+}
+try {
+	await main();
+} catch (error) {
+	console.error(error instanceof Error ? error.message : error);
+	if (!(error instanceof Error) || error.message !== usage) console.error(`\n${usage}`);
+	process.exitCode = 1;
+}
+//#endregion
+export {};