@tapi-dev/sdk 0.1.1 → 0.1.2

package/README.md

@@ -10,6 +10,55 @@ 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
+```
+
+It downloads the Windows installer, verifies the manifest SHA256, caches the installer locally, and runs it. The installer cache defaults to:
+
+```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:

package/dist/cli.d.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+export type StudioChannel = "pilot" | "stable" | "nightly";
+export interface StudioReleaseManifest {
+    product?: string;
+    version: string;
+    channel: string;
+    platform: string;
+    artifactName: string;
+    url: string;
+    sha256: string;
+    sizeBytes?: number;
+    minSdkVersion?: string;
+    builtAt?: string;
+    commit?: string;
+    commitShort?: string;
+    ref?: string;
+    installerKind?: string;
+}
+interface StudioCliOptions {
+    channel: StudioChannel;
+    manifestUrl: string;
+    cacheDir: string;
+    downloadOnly: boolean;
+    silent: boolean;
+    exePath?: string;
+}
+export declare function runCli(argv?: string[]): Promise<number>;
+export declare function parseStudioOptions(args: string[]): StudioCliOptions;
+export declare function getDefaultStudioCacheDir(): string;
+export declare function getStudioExecutableCandidates(): string[];
+export declare function validateStudioManifest(input: unknown): StudioReleaseManifest;
+export declare function compareVersions(left: string, right: string): number;
+export {};

package/dist/cli.js

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
+import { mkdir, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+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_CHANNEL = "pilot";
+const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
+const sdkVersion = readSdkVersion();
+export async function runCli(argv = process.argv.slice(2)) {
+    const [command, subcommand, ...rest] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(sdkVersion);
+        return 0;
+    }
+    if (command === "doctor") {
+        if (hasHelpFlag([subcommand, ...rest])) {
+            printStudioHelp();
+            return 0;
+        }
+        return runDoctor(parseStudioOptions([subcommand, ...rest].filter(Boolean)));
+    }
+    if (command !== "studio") {
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        return 1;
+    }
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        printStudioHelp();
+        return 0;
+    }
+    if (hasHelpFlag(rest)) {
+        printStudioHelp();
+        return 0;
+    }
+    const options = parseStudioOptions(rest);
+    if (subcommand === "install") {
+        return installStudio(options);
+    }
+    if (subcommand === "open") {
+        return openStudio(options);
+    }
+    if (subcommand === "doctor") {
+        return runDoctor(options);
+    }
+    console.error(`Unknown studio command: ${subcommand}`);
+    printStudioHelp();
+    return 1;
+}
+export function parseStudioOptions(args) {
+    const raw = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg === "--channel") {
+            raw.channel = parseChannel(requireOptionValue(args, ++index, "--channel"));
+            continue;
+        }
+        if (arg.startsWith("--channel=")) {
+            raw.channel = parseChannel(arg.slice("--channel=".length));
+            continue;
+        }
+        if (arg === "--manifest") {
+            raw.manifestUrl = requireOptionValue(args, ++index, "--manifest");
+            continue;
+        }
+        if (arg.startsWith("--manifest=")) {
+            raw.manifestUrl = arg.slice("--manifest=".length);
+            continue;
+        }
+        if (arg === "--cache-dir") {
+            raw.cacheDir = resolve(requireOptionValue(args, ++index, "--cache-dir"));
+            continue;
+        }
+        if (arg.startsWith("--cache-dir=")) {
+            raw.cacheDir = resolve(arg.slice("--cache-dir=".length));
+            continue;
+        }
+        if (arg === "--exe") {
+            raw.exePath = resolve(requireOptionValue(args, ++index, "--exe"));
+            continue;
+        }
+        if (arg.startsWith("--exe=")) {
+            raw.exePath = resolve(arg.slice("--exe=".length));
+            continue;
+        }
+        if (arg === "--download-only") {
+            raw.downloadOnly = true;
+            continue;
+        }
+        if (arg === "--silent") {
+            raw.silent = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            continue;
+        }
+        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`;
+    return {
+        channel,
+        manifestUrl,
+        cacheDir: raw.cacheDir ?? getDefaultStudioCacheDir(),
+        downloadOnly: raw.downloadOnly ?? false,
+        silent: raw.silent ?? false,
+        exePath: raw.exePath ?? envString("TAPI_STUDIO_EXE"),
+    };
+}
+export function getDefaultStudioCacheDir() {
+    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", "Studio", "downloads");
+    }
+    return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tapi", "studio");
+}
+export function getStudioExecutableCandidates() {
+    const candidates = [
+        process.env.TAPI_STUDIO_EXE,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "Tapi Studio", "Tapi Studio.exe") : undefined,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "Programs", "Tapi Studio", "Tapi Studio.exe") : undefined,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "com.tapi.studio", "Tapi Studio.exe") : undefined,
+        process.env.ProgramFiles ? join(process.env.ProgramFiles, "Tapi Studio", "Tapi Studio.exe") : undefined,
+        process.env["ProgramFiles(x86)"] ? join(process.env["ProgramFiles(x86)"], "Tapi Studio", "Tapi Studio.exe") : undefined,
+    ];
+    return [...new Set(candidates.filter((candidate) => Boolean(candidate)))];
+}
+export function validateStudioManifest(input) {
+    if (!input || typeof input !== "object") {
+        throw new Error("Studio manifest response was not a JSON object.");
+    }
+    const record = input;
+    const manifest = {
+        product: optionalString(record, "product"),
+        version: requiredString(record, "version"),
+        channel: requiredString(record, "channel"),
+        platform: requiredString(record, "platform"),
+        artifactName: requiredString(record, "artifactName"),
+        url: requiredString(record, "url"),
+        sha256: requiredString(record, "sha256").toLowerCase(),
+        sizeBytes: optionalNumber(record, "sizeBytes"),
+        minSdkVersion: optionalString(record, "minSdkVersion"),
+        builtAt: optionalString(record, "builtAt"),
+        commit: optionalString(record, "commit"),
+        commitShort: optionalString(record, "commitShort"),
+        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.");
+    }
+    return manifest;
+}
+export function compareVersions(left, right) {
+    const leftParts = versionCore(left);
+    const rightParts = versionCore(right);
+    const maxLength = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftValue = leftParts[index] ?? 0;
+        const rightValue = rightParts[index] ?? 0;
+        if (leftValue > rightValue) {
+            return 1;
+        }
+        if (leftValue < rightValue) {
+            return -1;
+        }
+    }
+    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}`);
+        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;
+}
+async function openStudio(options) {
+    ensureWindowsHost();
+    const exePath = options.exePath ?? getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
+    if (!exePath || !existsSync(exePath)) {
+        console.error("Tapi Studio executable was not found.");
+        console.error("Run `npx tapi studio install --channel pilot`, or set TAPI_STUDIO_EXE to the installed executable path.");
+        return 1;
+    }
+    const child = spawn(exePath, [], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: false,
+    });
+    child.unref();
+    console.log(`Opened Tapi Studio: ${exePath}`);
+    return 0;
+}
+async function runDoctor(options) {
+    console.log(`Tapi SDK: ${sdkVersion}`);
+    console.log(`Node: ${process.version}`);
+    console.log(`Platform: ${process.platform}/${process.arch}`);
+    console.log(`Studio channel: ${options.channel}`);
+    console.log(`Studio manifest: ${options.manifestUrl}`);
+    console.log(`Studio cache: ${options.cacheDir}`);
+    const exePath = options.exePath ?? getStudioExecutableCandidates().find((candidate) => existsSync(candidate));
+    console.log(`Studio executable: ${exePath && existsSync(exePath) ? exePath : "not found"}`);
+    try {
+        const manifest = await fetchStudioManifest(options.manifestUrl);
+        ensureCompatibleManifest(manifest);
+        console.log(`Latest Studio: ${manifest.version} (${manifest.platform})`);
+    }
+    catch (error) {
+        console.log(`Latest Studio: unavailable (${formatError(error)})`);
+        return 1;
+    }
+    return 0;
+}
+async function fetchStudioManifest(manifestUrl, fetchImpl = fetch) {
+    const response = await fetchImpl(manifestUrl, {
+        headers: {
+            Accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch Studio manifest: HTTP ${response.status}`);
+    }
+    return validateStudioManifest(await response.json());
+}
+async function downloadAndVerify(url, destination, expectedSha256) {
+    const partialPath = `${destination}.partial`;
+    await downloadFile(url, partialPath);
+    const actualSha256 = await sha256File(partialPath);
+    if (actualSha256 !== expectedSha256.toLowerCase()) {
+        await unlinkIfExists(partialPath);
+        throw new Error(`Studio installer checksum mismatch. Expected ${expectedSha256}, got ${actualSha256}.`);
+    }
+    await rename(partialPath, destination);
+    console.log(`Verified SHA256: ${actualSha256}`);
+}
+async function downloadFile(url, destination) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download Studio installer: HTTP ${response.status}`);
+    }
+    if (!response.body) {
+        throw new Error("Studio installer response did not include a body.");
+    }
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
+}
+async function hasVerifiedCachedInstaller(path, expectedSha256) {
+    if (!existsSync(path)) {
+        return false;
+    }
+    return (await sha256File(path)) === expectedSha256.toLowerCase();
+}
+async function sha256File(path) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+}
+async function runProcess(command, args) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        child.once("error", rejectPromise);
+        child.once("exit", (code) => {
+            if (code === 0) {
+                resolvePromise();
+            }
+            else {
+                rejectPromise(new Error(`Process exited with code ${code ?? "unknown"}.`));
+            }
+        });
+    });
+}
+function ensureWindowsHost() {
+    if (process.platform !== "win32" || process.arch !== "x64") {
+        throw new Error("Tapi Studio desktop installer is currently published for Windows x64 only.");
+    }
+}
+function ensureCompatibleManifest(manifest) {
+    if (manifest.platform !== SUPPORTED_STUDIO_PLATFORM) {
+        throw new Error(`This SDK expected ${SUPPORTED_STUDIO_PLATFORM}, but the manifest points to ${manifest.platform}.`);
+    }
+    if (manifest.minSdkVersion && compareVersions(sdkVersion, manifest.minSdkVersion) < 0) {
+        throw new Error(`Tapi Studio ${manifest.version} requires @tapi-dev/sdk >= ${manifest.minSdkVersion}; installed SDK is ${sdkVersion}.`);
+    }
+}
+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 parseChannel(value) {
+    if (value === "pilot" || value === "stable" || value === "nightly") {
+        return value;
+    }
+    throw new Error(`Invalid Studio channel: ${value}. Expected pilot, stable, or nightly.`);
+}
+function requireOptionValue(args, index, option) {
+    const value = args[index];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${option} requires a value.`);
+    }
+    return value;
+}
+function requiredString(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Studio manifest is missing required string field: ${field}`);
+    }
+    return value.trim();
+}
+function optionalString(record, field) {
+    const value = record[field];
+    if (typeof value === "string" && value.trim()) {
+        return value.trim();
+    }
+    return undefined;
+}
+function optionalNumber(record, field) {
+    const value = record[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    return undefined;
+}
+function envString(name) {
+    const value = process.env[name];
+    return value && value.trim() ? value.trim() : undefined;
+}
+function hasHelpFlag(args) {
+    return args.some((arg) => arg === "--help" || arg === "-h");
+}
+function versionCore(version) {
+    return version
+        .split("-")[0]
+        .split(".")
+        .map((part) => Number.parseInt(part, 10))
+        .map((part) => (Number.isFinite(part) ? part : 0));
+}
+async function unlinkIfExists(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+function readSdkVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (!packageJson.version) {
+        throw new Error("Could not read @tapi-dev/sdk package version.");
+    }
+    return packageJson.version;
+}
+function printHelp() {
+    console.log(`Tapi CLI
+
+Usage:
+  tapi studio install [--channel pilot] [--manifest URL]
+  tapi studio open
+  tapi studio doctor
+  tapi doctor
+
+Commands:
+  studio install  Download, verify, and run the Tapi Studio installer
+  studio open     Open an installed Tapi Studio desktop app
+  studio doctor   Check local SDK and Studio release configuration
+  doctor          Alias for studio doctor
+`);
+}
+function printStudioHelp() {
+    console.log(`Tapi Studio commands
+
+Usage:
+  tapi studio install [options]
+  tapi studio open [options]
+  tapi studio doctor [options]
+
+Options:
+  --channel <name>      Release channel: pilot, stable, or nightly
+  --manifest <url>      Exact release manifest URL
+  --cache-dir <path>    Installer download cache directory
+  --download-only       Download and verify without running the installer
+  --silent              Run the NSIS installer with /S
+  --exe <path>          Tapi Studio executable path for open/doctor
+`);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isCliEntrypoint() {
+    const invokedPath = process.argv[1];
+    return Boolean(invokedPath && resolve(invokedPath) === fileURLToPath(import.meta.url));
+}
+if (isCliEntrypoint()) {
+    runCli().then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        console.error(formatError(error));
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "tapi": "dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "dist"
   ],
@@ -23,6 +29,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^20.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   }