@hypertabai/mcp 0.2.0 → 1.0.0

package/dist/surfaces/detect.d.ts

@@ -0,0 +1,20 @@
+export type SurfaceFramework = 'vite-react' | 'vite' | 'astro-static' | 'plain-static' | 'unsupported-server' | 'unknown';
+export interface SurfaceProjectDetection {
+    root: string;
+    packageJsonPath: string | null;
+    packageManager: string | null;
+    framework: SurfaceFramework;
+    supported: boolean;
+    staticOutput: boolean;
+    outputDir: string;
+    outputExists: boolean;
+    outputFiles: string[];
+    buildCommand: string | null;
+    reason: string;
+    guidance: string | null;
+}
+export declare function detectSurfaceProject(input: {
+    directory: string;
+    outDir?: string;
+}): Promise<SurfaceProjectDetection>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/surfaces/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/surfaces/detect.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,MAAM,GACN,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,SAAS,CAAA;AAEZ,MAAM,WAAW,uBAAuB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,SAAS,EAAE,gBAAgB,CAAA;IAC3B,SAAS,EAAE,OAAO,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,OAAO,CAAA;IACrB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AA2BD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IACjD,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAuBnC"}

package/dist/surfaces/detect.js

@@ -0,0 +1,130 @@
+import { access, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import fg from 'fast-glob';
+const SERVER_FRAMEWORKS = new Set([
+    'next',
+    '@sveltejs/kit',
+    'nuxt',
+    '@remix-run/node',
+    '@remix-run/react',
+    'express',
+    'fastify',
+]);
+export async function detectSurfaceProject(input) {
+    const root = resolve(input.directory);
+    const packageJson = await readPackageJson(root);
+    const decision = await decideFramework(root, packageJson);
+    const outputDir = resolve(root, input.outDir ?? decision.defaultOutputDir);
+    const outputFiles = await listOutputFiles(outputDir);
+    const staticOutput = outputFiles.includes('index.html');
+    const outputExists = await pathExists(outputDir);
+    return {
+        root,
+        packageJsonPath: packageJson ? join(root, 'package.json') : null,
+        packageManager: await detectPackageManager(root, packageJson),
+        framework: decision.framework,
+        supported: decision.supported,
+        staticOutput,
+        outputDir,
+        outputExists,
+        outputFiles,
+        buildCommand: packageJson?.scripts.build ?? null,
+        reason: buildReason(decision, outputExists, staticOutput, outputDir),
+        guidance: decision.guidance,
+    };
+}
+async function decideFramework(root, packageJson) {
+    if (!packageJson) {
+        if (await pathExists(join(root, 'index.html'))) {
+            return supported('plain-static', '.', 'Plain static HTML project detected.');
+        }
+        return unsupported('unknown', '.', 'No package.json or root index.html was found.', 'Create a static dashboard project, or run the command from a directory with package.json or index.html.');
+    }
+    const deps = dependencyNames(packageJson);
+    const serverDependency = [...SERVER_FRAMEWORKS].find((name) => deps.has(name));
+    if (serverDependency) {
+        return unsupported('unsupported-server', 'dist', `${serverDependency} looks like a server app, which Hypertab does not host in v1.`, 'Convert the dashboard to a static browser app, preferably Vite + React, and move backend work into Hypertab endpoints, tables, smart columns, or agent commands.');
+    }
+    if (deps.has('vite')) {
+        const framework = deps.has('react') || deps.has('@vitejs/plugin-react') ? 'vite-react' : 'vite';
+        return supported(framework, 'dist', `${framework} project detected.`);
+    }
+    if (deps.has('astro'))
+        return supported('astro-static', 'dist', 'Astro static project detected.');
+    if (await pathExists(join(root, 'index.html')))
+        return supported('plain-static', '.', 'Plain static HTML project detected.');
+    return unsupported('unknown', 'dist', 'No supported static dashboard framework was detected.', 'Use Vite, Astro static, or plain HTML for v1 Hypertab surface hosting.');
+}
+function supported(framework, defaultOutputDir, reason) {
+    return { framework, supported: true, defaultOutputDir, reason, guidance: null };
+}
+function unsupported(framework, defaultOutputDir, reason, guidance) {
+    return { framework, supported: false, defaultOutputDir, reason, guidance };
+}
+function dependencyNames(packageJson) {
+    return new Set([...Object.keys(packageJson.dependencies), ...Object.keys(packageJson.devDependencies)]);
+}
+async function readPackageJson(root) {
+    const path = join(root, 'package.json');
+    if (!(await pathExists(path)))
+        return null;
+    const raw = JSON.parse(await readFile(path, 'utf8'));
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const record = raw;
+    return {
+        scripts: stringRecord(record.scripts),
+        dependencies: stringRecord(record.dependencies),
+        devDependencies: stringRecord(record.devDependencies),
+        packageManager: typeof record.packageManager === 'string' ? record.packageManager : undefined,
+    };
+}
+function stringRecord(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(value)
+        .filter((entry) => typeof entry[1] === 'string')
+        .map(([key, val]) => [key, val]));
+}
+async function detectPackageManager(root, packageJson) {
+    if (packageJson?.packageManager)
+        return packageJson.packageManager;
+    if (await pathExists(join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (await pathExists(join(root, 'yarn.lock')))
+        return 'yarn';
+    if (await pathExists(join(root, 'bun.lockb')))
+        return 'bun';
+    if (await pathExists(join(root, 'package-lock.json')))
+        return 'npm';
+    return null;
+}
+async function listOutputFiles(outputDir) {
+    if (!(await pathExists(outputDir)))
+        return [];
+    return fg('**/*', {
+        cwd: outputDir,
+        onlyFiles: true,
+        dot: false,
+        ignore: ['node_modules/**', '.git/**'],
+    });
+}
+function buildReason(decision, outputExists, staticOutput, outputDir) {
+    if (!decision.supported)
+        return decision.reason;
+    if (!outputExists)
+        return `${decision.reason} Static output directory does not exist yet: ${outputDir}.`;
+    if (!staticOutput)
+        return `${decision.reason} Static output is missing index.html in ${outputDir}.`;
+    return `${decision.reason} Static output is ready at ${outputDir}.`;
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=detect.js.map

package/dist/surfaces/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/surfaces/detect.ts"],"names":[],"mappings":"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"}

package/dist/surfaces/index.d.ts

@@ -0,0 +1,35 @@
+import type { Command } from 'commander';
+export declare const DEFAULT_SURFACE_API_URL = "https://api.hypertab.ai";
+export interface SurfacePublishOptions {
+    apiKey?: string;
+    apiUrl: string;
+    directory: string;
+    outDir?: string;
+    slug?: string;
+    title?: string;
+    buildCommand?: string;
+    activate: boolean;
+    json: boolean;
+    timeoutMs?: number;
+}
+interface RawSurfacePublishOptions {
+    apiKey?: string;
+    apiUrl: string;
+    dir: string;
+    outDir?: string;
+    slug?: string;
+    title?: string;
+    build?: string;
+    activate: boolean;
+    json?: boolean;
+    timeoutMs?: number;
+}
+interface SurfaceCommandDependencies {
+    runPublish?: (options: SurfacePublishOptions) => Promise<number>;
+    exit?: (code: number) => void;
+}
+export declare function registerSurfacesCommand(program: Command, deps?: SurfaceCommandDependencies): void;
+export declare function normalizeSurfacePublishOptions(opts: RawSurfacePublishOptions): SurfacePublishOptions;
+export declare function runSurfacePublish(options: SurfacePublishOptions): Promise<number>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/surfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surfaces/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAWxC,eAAO,MAAM,uBAAuB,4BAA4B,CAAA;AAEhE,MAAM,WAAW,qBAAqB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,UAAU,wBAAwB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,UAAU,0BAA0B;IACnC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAChE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,0BAA+B,GAAG,IAAI,CA+BrG;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CAapG;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DvF"}

package/dist/surfaces/index.js

@@ -0,0 +1,117 @@
+import { runSurfaceBuildAndValidate } from './build.js';
+import { detectSurfaceProject } from './detect.js';
+import { createSurfacePublishBundle } from './package.js';
+import { DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS, publishSurfaceBundle, resolvePublishApiKey, resolvePublishIdentity, } from './publish-client.js';
+export const DEFAULT_SURFACE_API_URL = 'https://api.hypertab.ai';
+export function registerSurfacesCommand(program, deps = {}) {
+    const runPublish = deps.runPublish ?? runSurfacePublish;
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const surfaces = program
+        .command('surfaces')
+        .description('Build and manage hosted Hypertab internal surfaces')
+        .showHelpAfterError();
+    surfaces
+        .command('publish')
+        .description('Publish a static dashboard surface to Hypertab')
+        .option('-k, --api-key <key>', 'Hypertab API key (ht_sk_...). Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_SURFACE_API_URL)
+        .option('-d, --dir <path>', 'Project directory to inspect and build', '.')
+        .option('--out-dir <path>', 'Static build output directory, for example dist')
+        .option('--slug <slug>', 'Hosted surface slug')
+        .option('--title <title>', 'Hosted surface title')
+        .option('--build <command>', 'Build command to run before packaging')
+        .option('--no-activate', 'Upload without activating the new deployment')
+        .option('--json', 'Print machine-readable JSON output for agents')
+        .option('--timeout-ms <ms>', 'Publish API request timeout in milliseconds', parsePositiveIntOption, DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runPublish(normalizeSurfacePublishOptions(opts));
+        exit(code);
+    });
+}
+export function normalizeSurfacePublishOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        directory: opts.dir,
+        outDir: opts.outDir,
+        slug: opts.slug,
+        title: opts.title,
+        buildCommand: opts.build,
+        activate: opts.activate,
+        json: opts.json ?? false,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS,
+    };
+}
+export async function runSurfacePublish(options) {
+    const detection = await detectSurfaceProject({ directory: options.directory, outDir: options.outDir });
+    if (!detection.supported) {
+        writeFailure(options, 'SURFACE_PROJECT_UNSUPPORTED', detection.reason, { guidance: detection.guidance });
+        return 2;
+    }
+    const build = await runSurfaceBuildAndValidate({
+        directory: options.directory,
+        outDir: options.outDir,
+        buildCommand: options.buildCommand,
+        detection,
+    });
+    if (!build.ok) {
+        writeFailure(options, build.errorCode ?? 'SURFACE_BUILD_FAILED', build.message, {
+            stderr: build.stderr || undefined,
+        });
+        return 2;
+    }
+    const bundle = await createSurfacePublishBundle({ build });
+    const apiKey = resolvePublishApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'SURFACE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY. It must start with ht_sk_.');
+        return 2;
+    }
+    const identity = resolvePublishIdentity({ slug: options.slug, title: options.title, root: build.detection.root });
+    const published = await publishSurfaceBundle({
+        apiUrl: options.apiUrl,
+        apiKey,
+        slug: identity.slug,
+        title: identity.title,
+        activate: options.activate,
+        bundle,
+        timeoutMs: options.timeoutMs,
+    });
+    if (!published.ok) {
+        writeFailure(options, published.code, published.message, { status: published.status, details: published.details });
+        return 2;
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ success: true, data: published.data, meta: { slug: identity.slug, content_hash: bundle.contentHash } })}\n`);
+        return 0;
+    }
+    process.stdout.write([
+        `Published Hypertab surface '${identity.slug}'.`,
+        `Files: ${bundle.files.length}`,
+        `Bytes: ${bundle.totalBytes}`,
+        `Content hash: ${bundle.contentHash}`,
+        '',
+    ].join('\n'));
+    return 0;
+}
+function parsePositiveIntOption(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        throw new Error(`Expected a positive integer, received '${value}'.`);
+    return parsed;
+}
+function writeFailure(options, code, message, details) {
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ success: false, error: { code, message, details } })}\n`);
+        return;
+    }
+    process.stderr.write([
+        `Error: ${message}`,
+        `Code: ${code}`,
+        details?.stderr ? `stderr:\n${details.stderr}` : null,
+        details?.guidance ? `Guidance: ${details.guidance}` : null,
+        '',
+    ]
+        .filter((line) => line !== null)
+        .join('\n'));
+}
+//# sourceMappingURL=index.js.map

package/dist/surfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surfaces/index.ts"],"names":[],"mappings":"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"}

package/dist/surfaces/package.d.ts

@@ -0,0 +1,48 @@
+import type { SurfaceBuildValidationResult } from './build.js';
+export interface SurfaceManifestAsset {
+    path: string;
+    asset_type: 'entry' | 'asset' | 'source_map' | 'preview' | 'manifest';
+    mime_type: string;
+    size_bytes: number;
+    content_hash: string;
+    cache_policy: 'immutable' | 'short' | 'none';
+}
+export interface SurfacePublishFile {
+    path: string;
+    content_base64: string;
+    mime_type: string;
+    asset_type: SurfaceManifestAsset['asset_type'];
+    content_hash: string;
+}
+export interface SurfacePublishManifest {
+    schema_version: 1;
+    kind: 'hosted_static';
+    entry_path: string;
+    assets: SurfaceManifestAsset[];
+    routes: Array<{
+        path: string;
+        entry_path: string;
+    }>;
+    actions: [];
+    api: {
+        cors_mode: 'same_origin';
+        allowed_origins: [];
+        scopes: ['observe'];
+    };
+    build: {
+        framework?: string;
+        command?: string;
+        output_dir?: string;
+    };
+    metadata: Record<string, unknown>;
+}
+export interface SurfacePublishBundle {
+    manifest: SurfacePublishManifest;
+    files: SurfacePublishFile[];
+    totalBytes: number;
+    contentHash: string;
+}
+export declare function createSurfacePublishBundle(input: {
+    build: SurfaceBuildValidationResult;
+}): Promise<SurfacePublishBundle>;
+//# sourceMappingURL=package.d.ts.map

package/dist/surfaces/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/surfaces/package.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAA;AAG9D,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAA;IACrE,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,WAAW,GAAG,OAAO,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAA;IAC9C,YAAY,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,sBAAsB;IACtC,cAAc,EAAE,CAAC,CAAA;IACjB,IAAI,EAAE,eAAe,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAA;IAC9B,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,EAAE,EAAE,CAAA;IACX,GAAG,EAAE;QAAE,SAAS,EAAE,aAAa,CAAC;QAAC,eAAe,EAAE,EAAE,CAAC;QAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAA;KAAE,CAAA;IAC3E,KAAK,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,UAAU,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,sBAAsB,CAAA;IAChC,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACvD,KAAK,EAAE,4BAA4B,CAAA;CACnC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkChC"}

package/dist/surfaces/package.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { lookup } from 'mime-types';
+export async function createSurfacePublishBundle(input) {
+    const detection = input.build.detection;
+    if (!input.build.ok || !detection.staticOutput) {
+        throw new Error('Cannot create a publish manifest before static output is validated.');
+    }
+    const files = await Promise.all(detection.outputFiles.sort().map((path) => readPublishFile(detection, path)));
+    const assets = files.map((file) => ({
+        path: file.path,
+        asset_type: file.asset_type,
+        mime_type: file.mime_type,
+        size_bytes: Buffer.from(file.content_base64, 'base64').byteLength,
+        content_hash: file.content_hash,
+        cache_policy: cachePolicyFor(file.path, file.asset_type),
+    }));
+    const totalBytes = assets.reduce((sum, asset) => sum + asset.size_bytes, 0);
+    const contentHash = hashText(assets.map((asset) => `${asset.path}:${asset.content_hash}`).join('\n'));
+    return {
+        manifest: {
+            schema_version: 1,
+            kind: 'hosted_static',
+            entry_path: 'index.html',
+            assets,
+            routes: [{ path: '/', entry_path: 'index.html' }],
+            actions: [],
+            api: { cors_mode: 'same_origin', allowed_origins: [], scopes: ['observe'] },
+            build: buildMetadata(input.build),
+            metadata: { content_hash: contentHash, total_bytes: totalBytes },
+        },
+        files,
+        totalBytes,
+        contentHash,
+    };
+}
+async function readPublishFile(detection, path) {
+    const bytes = await readFile(join(detection.outputDir, path));
+    const mimeType = lookup(path) || 'application/octet-stream';
+    return {
+        path,
+        content_base64: bytes.toString('base64'),
+        mime_type: mimeType,
+        asset_type: assetTypeFor(path),
+        content_hash: hashBytes(bytes),
+    };
+}
+function assetTypeFor(path) {
+    if (path === 'index.html')
+        return 'entry';
+    if (path.endsWith('.map'))
+        return 'source_map';
+    if (path.endsWith('.webmanifest') || path === 'manifest.json')
+        return 'manifest';
+    return 'asset';
+}
+function cachePolicyFor(path, type) {
+    if (type === 'entry' || path.endsWith('.html'))
+        return 'none';
+    if (type === 'source_map')
+        return 'short';
+    return 'immutable';
+}
+function buildMetadata(build) {
+    const outputDir = relativeBuildOutput(build.detection);
+    return {
+        framework: build.detection.framework,
+        command: build.buildCommand ?? undefined,
+        output_dir: outputDir,
+    };
+}
+function relativeBuildOutput(detection) {
+    const value = relative(detection.root, detection.outputDir);
+    if (!value || value === '.')
+        return undefined;
+    const normalized = value.split(sep).join('/');
+    return normalized.startsWith('..') ? undefined : normalized;
+}
+function hashBytes(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function hashText(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+//# sourceMappingURL=package.js.map

package/dist/surfaces/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/surfaces/package.ts"],"names":[],"mappings":"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"}

package/dist/surfaces/publish-client.d.ts

@@ -0,0 +1,40 @@
+import type { SurfacePublishBundle } from './package.js';
+export declare const DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS = 60000;
+export interface SurfacePublishRequest {
+    apiUrl: string;
+    apiKey: string;
+    slug: string;
+    title: string;
+    activate: boolean;
+    bundle: SurfacePublishBundle;
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface SurfacePublishSuccess {
+    ok: true;
+    status: number;
+    data: unknown;
+}
+export interface SurfacePublishFailure {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export type SurfacePublishResponse = SurfacePublishSuccess | SurfacePublishFailure;
+export declare function resolvePublishIdentity(input: {
+    slug?: string;
+    title?: string;
+    root: string;
+}): {
+    slug: string;
+    title: string;
+};
+export declare function resolvePublishApiKey(input: {
+    apiKey?: string;
+    env?: NodeJS.ProcessEnv;
+}): string | null;
+export declare function publishSurfaceBundle(input: SurfacePublishRequest): Promise<SurfacePublishResponse>;
+//# sourceMappingURL=publish-client.d.ts.map

package/dist/surfaces/publish-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-client.d.ts","sourceRoot":"","sources":["../../src/surfaces/publish-client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAGxD,eAAO,MAAM,kCAAkC,QAAS,CAAA;AAExD,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,oBAAoB,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;CACb;AAED,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,GAAG,qBAAqB,CAAA;AAElF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAM9H;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAGvG;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoExG"}

package/dist/surfaces/publish-client.js

@@ -0,0 +1,111 @@
+import { basename } from 'node:path';
+import { buildClientOperationIdempotencyKey, OPERATION_IDEMPOTENCY_HEADER } from '../idempotency.js';
+// Bundle uploads carry base64 file content, so the default is more generous than the bridge client's 30s.
+export const DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS = 60_000;
+export function resolvePublishIdentity(input) {
+    const slug = input.slug ?? slugify(basename(input.root) || 'surface');
+    return {
+        slug,
+        title: input.title ?? titleFromSlug(slug),
+    };
+}
+export function resolvePublishApiKey(input) {
+    const key = input.apiKey ?? input.env?.HYPERTAB_API_KEY ?? process.env.HYPERTAB_API_KEY;
+    return key?.startsWith('ht_sk_') ? key : null;
+}
+export async function publishSurfaceBundle(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const idempotencyKey = buildClientOperationIdempotencyKey({
+        operation: 'surface.publish',
+        target: input.slug,
+        fingerprint: `${input.bundle.contentHash}:${input.activate ? 'activate' : 'draft'}`,
+        providedKey: input.idempotencyKey,
+    });
+    const timeoutMs = input.timeoutMs ?? DEFAULT_SURFACE_PUBLISH_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    let res;
+    let payload;
+    try {
+        res = await fetchImpl(`${input.apiUrl.replace(/\/$/, '')}/api/surfaces/publish`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`,
+                'Content-Type': 'application/json',
+                [OPERATION_IDEMPOTENCY_HEADER]: idempotencyKey,
+            },
+            body: JSON.stringify({
+                slug: input.slug,
+                title: input.title,
+                manifest: input.bundle.manifest,
+                files: input.bundle.files,
+                source_type: 'cli',
+                activate: input.activate,
+            }),
+            signal: controller.signal,
+        });
+        payload = await parseResponse(res);
+    }
+    catch (error) {
+        if (timedOut) {
+            return {
+                ok: false,
+                status: 0,
+                code: 'SURFACE_PUBLISH_TIMEOUT',
+                message: `Surface publish request timed out after ${timeoutMs}ms without a response. ` +
+                    'The Hypertab API may be stalled. Retry the publish (the upload carries an idempotency key), or pass --timeout-ms to wait longer.',
+                details: { timeout_ms: timeoutMs },
+            };
+        }
+        return {
+            ok: false,
+            status: 0,
+            code: 'SURFACE_PUBLISH_UNREACHABLE',
+            message: error instanceof Error ? error.message : 'Surface publish request failed before receiving a response.',
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok || payload.success !== true) {
+        const errorPayload = payload;
+        return {
+            ok: false,
+            status: res.status,
+            code: errorPayload.error?.code ?? 'SURFACE_PUBLISH_API_FAILED',
+            message: errorPayload.error?.message ?? `Surface publish API failed with HTTP ${res.status}.`,
+            details: errorPayload.error?.details,
+        };
+    }
+    return { ok: true, status: res.status, data: payload.data };
+}
+async function parseResponse(res) {
+    const text = await res.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { success: false, error: { code: 'SURFACE_PUBLISH_API_INVALID_JSON', message: text.slice(0, 500) } };
+    }
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'surface';
+}
+function titleFromSlug(slug) {
+    return slug
+        .split('-')
+        .filter(Boolean)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join(' ');
+}
+//# sourceMappingURL=publish-client.js.map

package/dist/surfaces/publish-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-client.js","sourceRoot":"","sources":["../../src/surfaces/publish-client.ts"],"names":[],"mappings":"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"}