@tapi-dev/sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,189 +1,195 @@
-# TAPI JavaScript SDK
-
-Official JavaScript and TypeScript client for TAPI developer APIs.
-
-## Install
-
-```bash
-npm install @tapi-dev/sdk
-```
-
-This package is ESM-first and works in runtimes with `fetch`, including modern Node.js and browser-like server runtimes.
-
-## Install Tapi Studio
-
-Tapi Studio is the desktop app used to author and test local Tapi integrations. Install the SDK first, then use the bundled CLI:
-
-```bash
-npm install @tapi-dev/sdk
-npx tapi studio install --channel pilot
-npx tapi studio open
-```
-
-You can also run the CLI directly from npm without adding the package first:
-
-```bash
-npx @tapi-dev/sdk studio install --channel pilot
-```
-
+# TAPI JavaScript SDK
+
+Official JavaScript and TypeScript client for TAPI developer APIs.
+
+## Install
+
+```bash
+npm install @tapi-dev/sdk
+```
+
+This package is ESM-first and works in runtimes with `fetch`, including modern Node.js and browser-like server runtimes.
+
+## Install Tapi Studio
+
+Tapi Studio is the desktop app used to author and test local Tapi integrations. Install the SDK first, then use the bundled CLI:
+
+```bash
+npm install @tapi-dev/sdk
+npx tapi studio install --channel pilot
+npx tapi studio open
+```
+
+You can also run the CLI directly from npm without adding the package first:
+
+```bash
+npx @tapi-dev/sdk studio install --channel pilot
+```
+
 The CLI reads the release manifest from:
-
-```text
-https://downloads.tapi.dev/studio/channels/pilot/latest.json
-```
-
+
+```text
+https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+```
+
 It downloads the Windows installer, verifies the manifest SHA256, caches the installer locally, and runs it. The installer cache defaults to:
-
-```text
+
+```text
 %LOCALAPPDATA%\Tapi\Studio\downloads
 ```
 
-Useful commands:
-
-```bash
-npx tapi studio install --channel pilot
-npx tapi studio install --channel pilot --download-only
-npx tapi studio install --manifest https://downloads.tapi.dev/studio/channels/pilot/latest.json
-npx tapi studio open
-npx tapi studio doctor
-```
-
-Environment overrides:
-
-```env
-TAPI_STUDIO_CHANNEL=pilot
-TAPI_STUDIO_MANIFEST_URL=https://downloads.tapi.dev/studio/channels/pilot/latest.json
-TAPI_DOWNLOADS_BASE_URL=https://downloads.tapi.dev
-TAPI_STUDIO_EXE=C:\Users\you\AppData\Local\Tapi Studio\Tapi Studio.exe
-```
-
-Tapi Studio desktop releases are currently published for Windows x64.
-
-## Quick Start
-
-Create one TAPI client in your app's server-side code:
-
-```ts
-import { TapiClient } from "@tapi-dev/sdk";
-
-export const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  appId: process.env.TAPI_APP_ID,
-});
-```
-
-Then call a TAPI website API:
-
-```ts
-const run = await tapi.websiteApis.run("brokerage.submitTrade", {
-  inputs: {
-    symbol: "AAPL",
-    quantity: 1,
-    side: "buy",
-  },
-});
-
-const completedRun = await tapi.runs.wait(run.id);
-console.log(completedRun.status, completedRun.result);
-```
-
-Do not expose `TAPI_API_KEY` in public browser bundles. Put the SDK behind your own backend route, server action, or job worker when using secret API keys.
-
-## Configuration
-
-```env
-TAPI_BASE_URL=https://your-tapi-api-host
-TAPI_API_KEY=tapi_your_api_key
-TAPI_APP_ID=your-app-id
-```
-
-`appId` is optional. If provided, the SDK sends it as the `X-Tapi-App` header.
-
-## Common Project Setup
-
-A typical application keeps the client in one small module:
-
-```text
-src/
-  lib/
-    tapi.ts
-```
-
-```ts
-// src/lib/tapi.ts
-import { TapiClient } from "@tapi-dev/sdk";
-
-export const tapi = new TapiClient({
-  baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
-  appId: process.env.TAPI_APP_ID,
-});
-```
-
-Application code should import this shared client instead of constructing a new client in every file.
-
-## Available Resources
-
-```ts
-await tapi.catalog.get();
-await tapi.runners.list();
-await tapi.runtime.requirements();
-
-const run = await tapi.websiteApis.run("apiName.requestKey", {
-  inputs: { example: true },
-  priority: 5,
-  runnerId: "runner-id",
-  idempotencyKey: "request-123",
-});
-
-await tapi.runs.get(run.id);
-await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
-await tapi.runs.cancel(run.id);
-```
-
-Website API requests are addressed as `<apiName>.<requestKey>`.
-
-## Errors
-
-Failed HTTP responses throw `TapiError`:
-
-```ts
-import { TapiError } from "@tapi-dev/sdk";
-
-try {
-  await tapi.catalog.get();
-} catch (error) {
-  if (error instanceof TapiError) {
-    console.error(error.status, error.code, error.details);
-  }
-  throw error;
-}
-```
-
-## TypeScript
-
-The package includes generated TypeScript declarations. Common exported types include:
-
-```ts
-import type {
-  RuntimeRequirements,
-  SdkCatalog,
-  TapiRun,
-  TapiRunner,
-  WebsiteApiRunRequest,
-} from "@tapi-dev/sdk";
-```
-
-## Local Development
-
-From this SDK directory:
-
-```bash
-npm ci
-npm test
-npm run build
-npm pack --dry-run
-```
-
-`npm pack --dry-run` shows the exact files that will be published.
+Tapi Studio includes the matching Tapi Service build. When the installer runs,
+it installs or replaces the local `tapi-service` Windows service with the
+version declared in the Studio manifest. Developers do not pick a service
+version separately; updating Studio updates the service version used by that
+project and by apps generated from that project.
+
+Useful commands:
+
+```bash
+npx tapi studio install --channel pilot
+npx tapi studio install --channel pilot --download-only
+npx tapi studio install --manifest https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+npx tapi studio open
+npx tapi studio doctor
+```
+
+Environment overrides:
+
+```env
+TAPI_STUDIO_CHANNEL=pilot
+TAPI_STUDIO_MANIFEST_URL=https://d4xaf52nfwiok.cloudfront.net/studio/channels/pilot/latest.json
+TAPI_DOWNLOADS_BASE_URL=https://d4xaf52nfwiok.cloudfront.net
+TAPI_STUDIO_EXE=C:\Users\you\AppData\Local\Tapi Studio\Tapi Studio.exe
+```
+
+Tapi Studio desktop releases are currently published for Windows x64.
+
+## Quick Start
+
+Create one TAPI client in your app's server-side code:
+
+```ts
+import { TapiClient } from "@tapi-dev/sdk";
+
+export const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  appId: process.env.TAPI_APP_ID,
+});
+```
+
+Then call a TAPI website API:
+
+```ts
+const run = await tapi.websiteApis.run("brokerage.submitTrade", {
+  inputs: {
+    symbol: "AAPL",
+    quantity: 1,
+    side: "buy",
+  },
+});
+
+const completedRun = await tapi.runs.wait(run.id);
+console.log(completedRun.status, completedRun.result);
+```
+
+Do not expose `TAPI_API_KEY` in public browser bundles. Put the SDK behind your own backend route, server action, or job worker when using secret API keys.
+
+## Configuration
+
+```env
+TAPI_BASE_URL=https://your-tapi-api-host
+TAPI_API_KEY=tapi_your_api_key
+TAPI_APP_ID=your-app-id
+```
+
+`appId` is optional. If provided, the SDK sends it as the `X-Tapi-App` header.
+
+## Common Project Setup
+
+A typical application keeps the client in one small module:
+
+```text
+src/
+  lib/
+    tapi.ts
+```
+
+```ts
+// src/lib/tapi.ts
+import { TapiClient } from "@tapi-dev/sdk";
+
+export const tapi = new TapiClient({
+  baseUrl: process.env.TAPI_BASE_URL!,
+  apiKey: process.env.TAPI_API_KEY!,
+  appId: process.env.TAPI_APP_ID,
+});
+```
+
+Application code should import this shared client instead of constructing a new client in every file.
+
+## Available Resources
+
+```ts
+await tapi.catalog.get();
+await tapi.runners.list();
+await tapi.runtime.requirements();
+
+const run = await tapi.websiteApis.run("apiName.requestKey", {
+  inputs: { example: true },
+  priority: 5,
+  runnerId: "runner-id",
+  idempotencyKey: "request-123",
+});
+
+await tapi.runs.get(run.id);
+await tapi.runs.wait(run.id, { intervalMs: 1000, timeoutMs: 300000 });
+await tapi.runs.cancel(run.id);
+```
+
+Website API requests are addressed as `<apiName>.<requestKey>`.
+
+## Errors
+
+Failed HTTP responses throw `TapiError`:
+
+```ts
+import { TapiError } from "@tapi-dev/sdk";
+
+try {
+  await tapi.catalog.get();
+} catch (error) {
+  if (error instanceof TapiError) {
+    console.error(error.status, error.code, error.details);
+  }
+  throw error;
+}
+```
+
+## TypeScript
+
+The package includes generated TypeScript declarations. Common exported types include:
+
+```ts
+import type {
+  RuntimeRequirements,
+  SdkCatalog,
+  TapiRun,
+  TapiRunner,
+  WebsiteApiRunRequest,
+} from "@tapi-dev/sdk";
+```
+
+## Local Development
+
+From this SDK directory:
+
+```bash
+npm ci
+npm test
+npm run build
+npm pack --dry-run
+```
+
+`npm pack --dry-run` shows the exact files that will be published.

package/dist/cli.d.ts

@@ -15,6 +15,12 @@ export interface StudioReleaseManifest {
     commitShort?: string;
     ref?: string;
     installerKind?: string;
+    bundledService?: {
+        product?: string;
+        version?: string;
+        source?: string;
+        manifestUrl?: string;
+    };
 }
 interface StudioCliOptions {
     channel: StudioChannel;
@@ -27,6 +33,19 @@ interface StudioCliOptions {
 export declare function runCli(argv?: string[]): Promise<number>;
 export declare function parseStudioOptions(args: string[]): StudioCliOptions;
 export declare function getDefaultStudioCacheDir(): string;
+export declare class CliWideEvent {
+    private readonly filePath;
+    private readonly startedAt;
+    private readonly data;
+    private readonly phases;
+    private constructor();
+    static create(eventName: string, initialFields?: Record<string, unknown>): Promise<CliWideEvent>;
+    phase(phase: string, fields?: Record<string, unknown>): Promise<void>;
+    finish(success: boolean, fields?: Record<string, unknown>): Promise<void>;
+    private write;
+}
+export declare function createCliWideEvent(eventName: string, initialFields?: Record<string, unknown>): Promise<CliWideEvent>;
+export declare function getCliWideEventRoot(): string;
 export declare function getStudioExecutableCandidates(): string[];
 export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
 export declare function compareVersions(left: string, right: string): number;

package/dist/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
-import { mkdir, rename, unlink } from "node:fs/promises";
+import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
-const DEFAULT_DOWNLOADS_BASE_URL = "https://downloads.tapi.dev";
+const DEFAULT_DOWNLOADS_BASE_URL = "https://d4xaf52nfwiok.cloudfront.net";
 const DEFAULT_CHANNEL = "pilot";
 const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
+const MAX_WIDE_EVENT_PROCESS_ROOTS = 5;
 const sdkVersion = readSdkVersion();
 export async function runCli(argv = process.argv.slice(2)) {
     const [command, subcommand, ...rest] = argv;
@@ -109,10 +111,11 @@ export function parseStudioOptions(args) {
         throw new Error(`Unknown option: ${arg}`);
     }
     const channel = raw.channel ?? parseChannel(envString("TAPI_STUDIO_CHANNEL") ?? DEFAULT_CHANNEL);
-    const downloadsBaseUrl = envString("TAPI_DOWNLOADS_BASE_URL") ?? DEFAULT_DOWNLOADS_BASE_URL;
-    const manifestUrl = raw.manifestUrl ??
-        envString("TAPI_STUDIO_MANIFEST_URL") ??
-        `${downloadsBaseUrl.replace(/\/+$/, "")}/studio/channels/${channel}/latest.json`;
+    const downloadsBaseUrl = normalizeHttpUrl(envString("TAPI_DOWNLOADS_BASE_URL") ?? DEFAULT_DOWNLOADS_BASE_URL, "TAPI_DOWNLOADS_BASE_URL");
+    const explicitManifestUrl = raw.manifestUrl ?? envString("TAPI_STUDIO_MANIFEST_URL");
+    const manifestUrl = explicitManifestUrl
+        ? normalizeHttpUrl(explicitManifestUrl, "Studio manifest URL")
+        : `${downloadsBaseUrl.replace(/\/+$/, "")}/studio/channels/${channel}/latest.json`;
     return {
         channel,
         manifestUrl,
@@ -130,6 +133,141 @@ export function getDefaultStudioCacheDir() {
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "studio");
 }
+export class CliWideEvent {
+    filePath;
+    startedAt = performance.now();
+    data;
+    phases = [];
+    constructor(filePath, eventName, initialFields) {
+        this.filePath = filePath;
+        this.data = {
+            event: eventName,
+            seq: 1,
+            timestamp: new Date().toISOString(),
+            trace_id: `cli_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+            actor: {
+                mode: "tapi_cli",
+                pid: process.pid,
+                cwd: process.cwd(),
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+            },
+            phases: this.phases,
+            ...initialFields,
+        };
+    }
+    static async create(eventName, initialFields = {}) {
+        try {
+            const root = getCliWideEventRoot();
+            await mkdir(root, { recursive: true });
+            const sessionDir = join(root, sessionDirName("tapi_cli"));
+            await mkdir(sessionDir, { recursive: true });
+            await pruneCliWideEventProcessRoots(root);
+            const filePath = join(sessionDir, `${safeEventFilename(eventName)}_${timeFilename(new Date())}.json`);
+            const event = new CliWideEvent(filePath, eventName, initialFields);
+            await event.phase("start");
+            return event;
+        }
+        catch {
+            return new CliWideEvent(undefined, eventName, initialFields);
+        }
+    }
+    async phase(phase, fields = {}) {
+        this.phases.push({
+            phase,
+            timestamp: new Date().toISOString(),
+            fields: sanitizeEventFields(fields),
+        });
+        this.data.phase = phase;
+        await this.write();
+    }
+    async finish(success, fields = {}) {
+        const durationMs = Math.round((performance.now() - this.startedAt) * 10) / 10;
+        this.data.duration_ms = durationMs;
+        this.data.outcome = success ? "success" : "error";
+        await this.phase(success ? "finish.success" : "finish.error", fields);
+    }
+    async write() {
+        if (!this.filePath) {
+            return;
+        }
+        try {
+            await writeFile(this.filePath, JSON.stringify(this.data, null, 2), "utf8");
+        }
+        catch {
+            // Diagnostics must never make the installer path fail.
+        }
+    }
+}
+export async function createCliWideEvent(eventName, initialFields = {}) {
+    return CliWideEvent.create(eventName, initialFields);
+}
+export function getCliWideEventRoot() {
+    const override = envString("TAPI_EVENTS_ROOT");
+    if (override) {
+        return override;
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ??
+            (process.env.USERPROFILE ? join(process.env.USERPROFILE, "AppData", "Local") : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "Tapi", "logs", "events");
+    }
+    return join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "tapi", "logs", "events");
+}
+async function pruneCliWideEventProcessRoots(root) {
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        const directories = await Promise.all(entries
+            .filter((entry) => entry.isDirectory())
+            .map(async (entry) => {
+            const path = join(root, entry.name);
+            try {
+                return { path, mtimeMs: (await stat(path)).mtimeMs };
+            }
+            catch {
+                return { path, mtimeMs: 0 };
+            }
+        }));
+        if (directories.length <= MAX_WIDE_EVENT_PROCESS_ROOTS) {
+            return;
+        }
+        directories.sort((left, right) => right.mtimeMs - left.mtimeMs || right.path.localeCompare(left.path));
+        await Promise.all(directories
+            .slice(MAX_WIDE_EVENT_PROCESS_ROOTS)
+            .map((entry) => rm(entry.path, { recursive: true, force: true })));
+    }
+    catch {
+        // Best-effort retention only.
+    }
+}
+function sessionDirName(role) {
+    const now = new Date();
+    const stamp = now
+        .toISOString()
+        .replace("T", "_")
+        .replace(/\.\d+Z$/, "")
+        .replace(/:/g, "-");
+    return `${stamp}_${role}_pid${process.pid}`;
+}
+function timeFilename(date) {
+    return date
+        .toISOString()
+        .split("T")[1]
+        .replace("Z", "")
+        .replace(/:/g, "-");
+}
+function safeEventFilename(eventName) {
+    return `001_${eventName.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\./g, "_")}`;
+}
+function sanitizeEventFields(fields) {
+    return JSON.parse(JSON.stringify(fields, (_key, value) => {
+        if (value instanceof Error) {
+            return errorDetails(value);
+        }
+        return value;
+    }));
+}
 export function getStudioExecutableCandidates() {
     const candidates = [
         process.env.TAPI_STUDIO_EXE,
@@ -152,7 +290,7 @@ export function validateStudioManifest(input) {
         channel: requiredString(record, "channel"),
         platform: requiredString(record, "platform"),
         artifactName: requiredString(record, "artifactName"),
-        url: requiredString(record, "url"),
+        url: normalizeHttpUrl(requiredString(record, "url"), "Studio manifest url"),
         sha256: requiredString(record, "sha256").toLowerCase(),
         sizeBytes: optionalNumber(record, "sizeBytes"),
         minSdkVersion: optionalString(record, "minSdkVersion"),
@@ -162,9 +300,6 @@ export function validateStudioManifest(input) {
         ref: optionalString(record, "ref"),
         installerKind: optionalString(record, "installerKind"),
     };
-    if (!/^https?:\/\//i.test(manifest.url)) {
-        throw new Error("Studio manifest url must be an absolute HTTP(S) URL.");
-    }
     if (!/^[a-f0-9]{64}$/i.test(manifest.sha256)) {
         throw new Error("Studio manifest sha256 must be a 64-character hex digest.");
     }
@@ -187,29 +322,84 @@ export function compareVersions(left, right) {
     return 0;
 }
 async function installStudio(options) {
-    ensureWindowsHost();
-    console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
-    const manifest = await fetchStudioManifest(options.manifestUrl);
-    ensureCompatibleManifest(manifest);
-    await mkdir(options.cacheDir, { recursive: true });
-    const installerPath = join(options.cacheDir, cachedInstallerName(manifest));
-    const verified = await hasVerifiedCachedInstaller(installerPath, manifest.sha256);
-    if (verified) {
-        console.log(`Using cached installer: ${installerPath}`);
-    }
-    else {
-        console.log(`Downloading Tapi Studio ${manifest.version}...`);
-        await downloadAndVerify(manifest.url, installerPath, manifest.sha256);
-    }
-    if (options.downloadOnly) {
-        console.log(`Downloaded installer: ${installerPath}`);
+    const event = await createCliWideEvent("tapi_cli.studio_install", {
+        sdk_version: sdkVersion,
+        options: installEventOptions(options),
+    });
+    try {
+        await event.phase("host.check", {
+            platform: process.platform,
+            arch: process.arch,
+        });
+        ensureWindowsHost();
+        console.log(`Fetching Tapi Studio ${options.channel} manifest...`);
+        await event.phase("manifest.fetch.start", {
+            manifestUrl: options.manifestUrl,
+            channel: options.channel,
+        });
+        const manifest = await fetchStudioManifest(options.manifestUrl);
+        await event.phase("manifest.fetch.success", {
+            manifest: manifestEventSummary(manifest),
+        });
+        ensureCompatibleManifest(manifest);
+        await event.phase("manifest.compatible", {
+            sdkVersion,
+            minSdkVersion: manifest.minSdkVersion,
+            platform: manifest.platform,
+        });
+        await mkdir(options.cacheDir, { recursive: true });
+        const installerPath = join(options.cacheDir, cachedInstallerName(manifest));
+        await event.phase("cache.check.start", {
+            cacheDir: options.cacheDir,
+            installerPath,
+        });
+        const verified = await hasVerifiedCachedInstaller(installerPath, manifest.sha256);
+        if (verified) {
+            console.log(`Using cached installer: ${installerPath}`);
+            await event.phase("cache.hit", { installerPath });
+        }
+        else {
+            await event.phase("cache.miss", { installerPath });
+            console.log(`Downloading Tapi Studio ${manifest.version}...`);
+            await event.phase("download.start", {
+                url: manifest.url,
+                destination: installerPath,
+                expectedSha256: manifest.sha256,
+            });
+            await downloadAndVerify(manifest.url, installerPath, manifest.sha256);
+            await event.phase("download.verified", {
+                installerPath,
+                expectedSha256: manifest.sha256,
+            });
+        }
+        if (options.downloadOnly) {
+            console.log(`Downloaded installer: ${installerPath}`);
+            await event.finish(true, {
+                installerPath,
+                downloadOnly: true,
+            });
+            return 0;
+        }
+        const installerArgs = options.silent ? ["/S"] : [];
+        console.log(`Starting Tapi Studio installer: ${installerPath}`);
+        await event.phase("installer.start", {
+            installerPath,
+            args: installerArgs,
+        });
+        await runProcess(installerPath, installerArgs);
+        console.log("Tapi Studio installer finished.");
+        await event.finish(true, {
+            installerPath,
+            downloadOnly: false,
+        });
         return 0;
     }
-    const installerArgs = options.silent ? ["/S"] : [];
-    console.log(`Starting Tapi Studio installer: ${installerPath}`);
-    await runProcess(installerPath, installerArgs);
-    console.log("Tapi Studio installer finished.");
-    return 0;
+    catch (error) {
+        await event.finish(false, {
+            error: errorDetails(error),
+        });
+        throw error;
+    }
 }
 async function openStudio(options) {
     ensureWindowsHost();
@@ -325,6 +515,31 @@ function cachedInstallerName(manifest) {
     const rawName = manifest.artifactName || basename(new URL(manifest.url).pathname) || `TapiStudioSetup-${manifest.version}.exe`;
     return rawName.replace(/[^A-Za-z0-9._-]/g, "_");
 }
+function installEventOptions(options) {
+    return {
+        channel: options.channel,
+        manifestUrl: options.manifestUrl,
+        cacheDir: options.cacheDir,
+        downloadOnly: options.downloadOnly,
+        silent: options.silent,
+        exePath: options.exePath,
+    };
+}
+function manifestEventSummary(manifest) {
+    return {
+        product: manifest.product,
+        version: manifest.version,
+        channel: manifest.channel,
+        platform: manifest.platform,
+        artifactName: manifest.artifactName,
+        url: manifest.url,
+        sha256: manifest.sha256,
+        sizeBytes: manifest.sizeBytes,
+        minSdkVersion: manifest.minSdkVersion,
+        commitShort: manifest.commitShort,
+        bundledService: manifest.bundledService,
+    };
+}
 function parseChannel(value) {
     if (value === "pilot" || value === "stable" || value === "nightly") {
         return value;
@@ -363,6 +578,23 @@ function envString(name) {
     const value = process.env[name];
     return value && value.trim() ? value.trim() : undefined;
 }
+function normalizeHttpUrl(value, label) {
+    const trimmed = value.trim();
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    try {
+        const url = new URL(withScheme);
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            throw new Error(`${label} must use HTTP or HTTPS.`);
+        }
+        return url.toString();
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("must use HTTP or HTTPS")) {
+            throw error;
+        }
+        throw new Error(`${label} must be a valid HTTP(S) URL.`);
+    }
+}
 function hasHelpFlag(args) {
     return args.some((arg) => arg === "--help" || arg === "-h");
 }
@@ -426,6 +658,49 @@ Options:
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function errorDetails(error) {
+    if (error instanceof Error) {
+        const details = {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+        const cause = error.cause;
+        if (cause) {
+            details.cause = serializeError(cause);
+        }
+        return details;
+    }
+    return {
+        message: String(error),
+    };
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        const record = error;
+        const details = {
+            name: error.name,
+            message: error.message,
+        };
+        for (const key of ["code", "errno", "syscall", "address", "port"]) {
+            const value = record[key];
+            if (value !== undefined) {
+                details[key] = value;
+            }
+        }
+        const cause = error.cause;
+        if (cause) {
+            details.cause = serializeError(cause);
+        }
+        return details;
+    }
+    if (error && typeof error === "object") {
+        return Object.fromEntries(Object.entries(error).filter(([, value]) => value !== undefined));
+    }
+    return {
+        message: String(error),
+    };
+}
 function isCliEntrypoint() {
     const invokedPath = process.argv[1];
     return Boolean(invokedPath && resolve(invokedPath) === fileURLToPath(import.meta.url));

package/dist/types.d.ts

@@ -31,7 +31,10 @@ export interface TapiRunner {
 }
 export interface RuntimeRequirements {
     daemonRequired: boolean;
+    serviceRequired?: boolean;
     localControlUrl?: string;
+    serviceName?: string;
+    serviceVersion?: string;
     windowsServiceName?: string;
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",