oneclient 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# oneclient
+
+One package for the complete OneClient TypeScript SDK and its developer CLI.
+
+```bash
+npm install oneclient
+npx oneclient login --email you@company.com
+npx oneclient init
+```
+
+The same package works in code:
+
+```ts
+import { createClient } from "oneclient";
+
+const one = createClient({
+  baseUrl: process.env.ONECLIENT_API_URL!,
+  serverKey: process.env.ONECLIENT_SERVER_KEY!,
+});
+
+const notes = await one.from("notes").select("id", "title").limit(20).execute();
+```
+
+Useful commands:
+
+```bash
+oneclient status
+oneclient projects
+oneclient usage
+oneclient deployments --environment env_...
+oneclient models
+oneclient billing:topup --usd 25
+oneclient doctor
+oneclient docs
+oneclient mcp
+```
+
+Interactive terminals receive a compact, colored interface. Pipes and CI receive stable JSON by
+default; `--json` makes that behavior explicit. Developer login credentials are stored in an
+owner-only local file. `sk_*` and `dp_*` credentials stay in environment variables and are never
+persisted by the CLI.
+
+Documentation: [one-client.com/docs](https://one-client.com/docs) · AI context:
+[one-client.com/llms.txt](https://one-client.com/llms.txt)

package/dist/artifact-create.d.ts

@@ -0,0 +1,15 @@
+import { type ArtifactManifest } from "@oneclient/contracts";
+export interface CreateArtifactOptions {
+    directory: string;
+    archivePath: string;
+    manifestPath: string;
+    framework: ArtifactManifest["framework"];
+    rootDirectory?: string;
+    entrypoint?: string;
+    buildCommand?: string;
+    outputDirectory?: string;
+    lockfile?: ArtifactManifest["lockfile"];
+    createdAt?: string;
+}
+export declare function createArtifact(options: CreateArtifactOptions): Promise<ArtifactManifest>;
+//# sourceMappingURL=artifact-create.d.ts.map

package/dist/artifact-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-create.d.ts","sourceRoot":"","sources":["../src/artifact-create.ts"],"names":[],"mappings":"AAIA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAOrF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkDD,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmF9F"}

package/dist/artifact-create.js

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readdir, realpath, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { artifactManifestSchema } from "@oneclient/contracts";
+import { create as createTar } from "tar";
+const maximumFiles = 20_000;
+const maximumFileBytes = 100 * 1024 * 1024;
+const maximumTotalBytes = 500 * 1024 * 1024;
+function artifactPath(root, absolute) {
+    const path = relative(root, absolute).split(sep).join("/");
+    if (!path ||
+        path.startsWith("/") ||
+        path.includes("\\") ||
+        path.split("/").some((part) => !part || part === "." || part === "..") ||
+        path.length > 1024)
+        throw new Error(`Unsafe artifact path: ${path || absolute}`);
+    return path;
+}
+function validatedManifestPath(path, label) {
+    if (path === undefined)
+        return undefined;
+    const normalized = path.split(sep).join("/");
+    if (normalized.startsWith("/") ||
+        normalized.includes("\\") ||
+        normalized.split("/").some((part) => !part || part === "." || part === "..") ||
+        normalized.length > 1024)
+        throw new Error(`${label} must be a safe relative path`);
+    return normalized;
+}
+function ignoredPath(path) {
+    const parts = path.split("/");
+    if (parts.some((part) => [".git", ".next", ".open-next", ".turbo", ".wrangler", "node_modules"].includes(part)))
+        return true;
+    const name = parts.at(-1) ?? "";
+    return (((name === ".env" || name.startsWith(".env.")) && name !== ".env.example") ||
+        name === ".dev.vars" ||
+        name.startsWith(".dev.vars."));
+}
+async function sha256File(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+export async function createArtifact(options) {
+    const rootDirectory = validatedManifestPath(options.rootDirectory, "rootDirectory");
+    const entrypoint = validatedManifestPath(options.entrypoint, "entrypoint");
+    const outputDirectory = validatedManifestPath(options.outputDirectory, "outputDirectory");
+    if (options.framework === "worker" && !entrypoint)
+        throw new Error("Worker artifacts require an entrypoint");
+    if (options.framework === "next-opennext" && !entrypoint)
+        throw new Error("OpenNext artifacts require a Worker entrypoint");
+    if ((options.framework === "vite" || options.framework === "next-opennext") && !outputDirectory)
+        throw new Error("Vite and OpenNext artifacts require an outputDirectory");
+    const root = await realpath(resolve(options.directory));
+    const archivePath = resolve(options.archivePath);
+    const manifestPath = resolve(options.manifestPath);
+    const excluded = new Set([archivePath, manifestPath]);
+    const files = [];
+    let totalBytes = 0;
+    async function walk(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const absolute = resolve(directory, entry.name);
+            if (excluded.has(absolute))
+                continue;
+            const path = artifactPath(root, absolute);
+            if (ignoredPath(path))
+                continue;
+            const metadata = await lstat(absolute);
+            if (metadata.isSymbolicLink())
+                throw new Error(`Artifact contains a symbolic link: ${path}`);
+            if (metadata.isDirectory()) {
+                await walk(absolute);
+                continue;
+            }
+            if (!metadata.isFile())
+                throw new Error(`Artifact contains a special file: ${path}`);
+            if (metadata.size > maximumFileBytes)
+                throw new Error(`Artifact file exceeds 100 MiB: ${path}`);
+            if (files.length >= maximumFiles)
+                throw new Error("Artifact contains more than 20,000 files");
+            totalBytes += metadata.size;
+            if (totalBytes > maximumTotalBytes)
+                throw new Error("Artifact exceeds 500 MiB");
+            files.push({
+                path,
+                size: metadata.size,
+                sha256: await sha256File(absolute),
+                mode: (metadata.mode & 0o111) === 0 ? "file" : "executable",
+            });
+        }
+    }
+    await walk(root);
+    if (!files.length)
+        throw new Error("Artifact directory contains no deployable files");
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    await mkdir(dirname(archivePath), { recursive: true });
+    await createTar({
+        cwd: root,
+        file: archivePath,
+        follow: false,
+        gzip: false,
+        noMtime: true,
+        portable: true,
+        strict: true,
+    }, files.map((file) => file.path));
+    const manifest = artifactManifestSchema.parse({
+        version: 1,
+        framework: options.framework,
+        ...(rootDirectory ? { rootDirectory } : {}),
+        ...(entrypoint ? { entrypoint } : {}),
+        ...(options.buildCommand ? { buildCommand: options.buildCommand } : {}),
+        ...(outputDirectory ? { outputDirectory } : {}),
+        ...(options.lockfile ? { lockfile: options.lockfile } : {}),
+        files,
+        totalBytes,
+        source: { kind: "cli" },
+        createdAt: options.createdAt ?? new Date().toISOString(),
+        signature: "0".repeat(64),
+    });
+    await mkdir(dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return manifest;
+}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export * from "@oneclient/sdk";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/client.js

@@ -0,0 +1 @@
+export * from "@oneclient/sdk";

package/dist/credential-routing.d.ts

@@ -0,0 +1,5 @@
+import type { ServerKeyScope } from "@oneclient/sdk";
+export declare function deployTokenFromEnvironment(environment?: NodeJS.ProcessEnv): string | undefined;
+export declare function serverKeyFromEnvironment(environment?: NodeJS.ProcessEnv): string | undefined;
+export declare function parseServerKeyScopes(prefix: "pk" | "sk", value: string | undefined): ServerKeyScope[] | undefined;
+//# sourceMappingURL=credential-routing.d.ts.map

package/dist/credential-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-routing.d.ts","sourceRoot":"","sources":["../src/credential-routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,wBAAgB,0BAA0B,CACxC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,MAAM,GAAG,SAAS,CAGpB;AAYD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,cAAc,EAAE,GAAG,SAAS,CAc9B"}

package/dist/credential-routing.js

@@ -0,0 +1,32 @@
+export function deployTokenFromEnvironment(environment = process.env) {
+    const token = environment.ONECLIENT_DEPLOY_TOKEN ?? environment.ONECLIENT_TOKEN;
+    return token?.startsWith("dp_") ? token : undefined;
+}
+export function serverKeyFromEnvironment(environment = process.env) {
+    const token = environment.ONECLIENT_SERVER_KEY ?? environment.ONECLIENT_TOKEN;
+    return token?.startsWith("sk_") ? token : undefined;
+}
+const serverKeyScopes = new Set([
+    "data:*",
+    "storage:*",
+    "kv:*",
+    "jobs:*",
+    "email:*",
+    "ai:*",
+    "analytics:*",
+]);
+export function parseServerKeyScopes(prefix, value) {
+    if (prefix === "pk") {
+        if (value)
+            throw new Error("pk keys do not accept server scopes");
+        return undefined;
+    }
+    const scopes = [...new Set((value ?? "").split(",").map((scope) => scope.trim()))].filter(Boolean);
+    if (!scopes.length)
+        throw new Error("sk keys require --scopes with at least one scope");
+    for (const scope of scopes) {
+        if (!serverKeyScopes.has(scope))
+            throw new Error(`Unsupported server-key scope: ${scope}`);
+    }
+    return scopes;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,10 @@
+export interface DeveloperCredentials {
+    apiUrl: string;
+    sessionToken: string;
+}
+export declare function credentialsPath(environment?: NodeJS.ProcessEnv): string;
+export declare function readDeveloperCredentials(path?: string): Promise<DeveloperCredentials | null>;
+export declare function writeDeveloperCredentials(credentials: DeveloperCredentials, path?: string): Promise<void>;
+export declare function clearDeveloperCredentials(path?: string): Promise<boolean>;
+export declare function validateApiUrl(value: string): string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAIpF;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,SAAoB,GACvB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAwBtC;AAED,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,oBAAoB,EACjC,IAAI,SAAoB,GACvB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,yBAAyB,CAAC,IAAI,SAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ1F;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpD"}

package/dist/credentials.js

@@ -0,0 +1,88 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function credentialsPath(environment = process.env) {
+    const configDirectory = environment.ONECLIENT_CONFIG_DIR ?? environment.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(configDirectory, "oneclient", "credentials.json");
+}
+export async function readDeveloperCredentials(path = credentialsPath()) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return null;
+        throw error;
+    }
+    if (process.platform !== "win32") {
+        const metadata = await stat(path);
+        if ((metadata.mode & 0o077) !== 0) {
+            throw new Error(`Refusing to read ${path}: credentials must not be accessible by group or other users`);
+        }
+    }
+    const parsed = JSON.parse(contents);
+    if (typeof parsed.apiUrl !== "string" || typeof parsed.sessionToken !== "string") {
+        throw new Error(`Invalid OneClient credentials file: ${path}`);
+    }
+    return {
+        apiUrl: validateApiUrl(parsed.apiUrl),
+        sessionToken: validateSessionToken(parsed.sessionToken),
+    };
+}
+export async function writeDeveloperCredentials(credentials, path = credentialsPath()) {
+    const normalized = {
+        apiUrl: validateApiUrl(credentials.apiUrl),
+        sessionToken: validateSessionToken(credentials.sessionToken),
+    };
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporaryPath = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(normalized, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporaryPath, path);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+export async function clearDeveloperCredentials(path = credentialsPath()) {
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return false;
+        throw error;
+    }
+}
+export function validateApiUrl(value) {
+    const url = new URL(value);
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+        throw new Error("The OneClient API URL must use HTTPS (HTTP is allowed only for localhost)");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("The OneClient API URL cannot contain credentials, a query, or a fragment");
+    }
+    return url.toString().replace(/\/$/, "");
+}
+function validateSessionToken(value) {
+    const token = value.trim();
+    if (token.length < 16 || /\s/.test(token))
+        throw new Error("Invalid developer session token");
+    return token;
+}
+function isMissingFile(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/deployment-wait.d.ts

@@ -0,0 +1,16 @@
+export type DeploymentBuildStatus = "uploading" | "queued" | "building" | "ready" | "failed" | "promoted" | "superseded";
+export interface DeploymentStatusResult {
+    id: string;
+    status: DeploymentBuildStatus;
+}
+interface WaitForDeploymentOptions {
+    getStatus: () => Promise<DeploymentStatusResult>;
+    timeoutMs: number;
+    pollIntervalMs?: number;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+export declare function waitForDeployment(deploymentId: string, options: WaitForDeploymentOptions): Promise<DeploymentStatusResult>;
+export declare function deploymentWaitTimeout(value: string): number;
+export {};
+//# sourceMappingURL=deployment-wait.d.ts.map

package/dist/deployment-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-wait.d.ts","sourceRoot":"","sources":["../src/deployment-wait.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAC/B,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED,UAAU,wBAAwB;IAChC,SAAS,EAAE,MAAM,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAID,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3D"}

package/dist/deployment-wait.js

@@ -0,0 +1,31 @@
+const pendingStatuses = new Set(["uploading", "queued", "building"]);
+export async function waitForDeployment(deploymentId, options) {
+    if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)
+        throw new TypeError("Deployment wait timeout must be a positive integer");
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs <= 0)
+        throw new TypeError("Deployment poll interval must be a positive integer");
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const deadline = now() + options.timeoutMs;
+    while (true) {
+        const deployment = await options.getStatus();
+        if (deployment.id !== deploymentId)
+            throw new Error(`Deployment status response did not match ${deploymentId}`);
+        if (deployment.status === "failed")
+            throw new Error(`Deployment ${deploymentId} failed; inspect it with oneclient deployment:logs`);
+        if (!pendingStatuses.has(deployment.status))
+            return deployment;
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw new Error(`Timed out waiting for deployment ${deploymentId}; it may still finish in the background`);
+        await sleep(Math.min(pollIntervalMs, remaining));
+    }
+}
+export function deploymentWaitTimeout(value) {
+    const seconds = Number(value);
+    if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 3_600)
+        throw new TypeError("--wait-timeout must be an integer from 1 to 3600 seconds");
+    return seconds * 1_000;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}