settlemesh 0.1.34

package/README.md

@@ -0,0 +1,178 @@
+# SettleMesh CLI
+
+SettleMesh is a CLI-first tool platform for developers, scripts, and AI agents. The npm package and primary command are both `settlemesh`.
+
+## Install
+
+For AI agents, clean terminals, and project-specific deploys, prefer a project-local latest install. This avoids stale global binaries:
+
+```bash
+npm install settlemesh@latest --prefer-online
+./node_modules/.bin/settlemesh doctor --require-latest
+./node_modules/.bin/settlemesh recipes
+```
+
+Global install is also supported for interactive use:
+
+```bash
+npm install -g settlemesh
+settlemesh doctor
+```
+
+The package exposes compatibility aliases:
+
+```bash
+settlemesh --version
+settle --version
+settlekit --version
+kit --version
+```
+
+Project-local install also works:
+
+```bash
+npm install settlemesh@latest --prefer-online
+./node_modules/.bin/settlemesh help
+```
+
+## Login
+
+```bash
+settlemesh login
+```
+
+For CI, scripts, and hosted agents:
+
+```bash
+export SETTLE_API_KEY="sk_..."
+```
+
+Use `SETTLE_BASE_URL=http://localhost:8080` for local development, and `SETTLE_REQUEST_TIMEOUT=90s` for slow provider calls.
+
+## Use Tools
+
+Always use discovery before calling tools:
+
+```bash
+settlemesh help --json
+settlemesh recipes
+settlemesh tool list --json
+settlemesh tool show web.search --json
+```
+
+For a no-context agent, start with the built-in golden paths:
+
+```bash
+npm install settlemesh@latest --prefer-online
+./node_modules/.bin/settlemesh doctor --require-latest
+./node_modules/.bin/settlemesh recipes
+./node_modules/.bin/settlemesh search "build app with login database api command"
+./node_modules/.bin/settlemesh services show app-project-backends --json
+```
+
+`settlemesh recipes` covers the shortest flows for full-stack app deploys, App API/CLI commands, browser bridge URLs, hosted agents, and local worker offers.
+
+Call a tool with JSON input:
+
+```bash
+settlemesh tool call web.search \
+  --input '{"q":"SettleMesh","count":5}' \
+  --json
+```
+
+Generate an image task:
+
+```bash
+settlemesh tool call image.gpt-image-2 \
+  --input '{"prompt":"A clean product photo of a ceramic tea cup","size":"1:1"}' \
+  --json
+```
+
+Poll async media:
+
+```bash
+settlemesh tool events image_... --json
+```
+
+Upload a local image for image-to-image:
+
+```bash
+settlemesh files upload ./input.png --json
+settlemesh tool call image.gpt-image-2 \
+  --input '{"prompt":"Turn this into a clean product photo","size":"1:1"}' \
+  --image-file ./input.png \
+  --json
+```
+
+## Credits
+
+```bash
+settlemesh credits balance --json
+settlemesh credits ledger --json
+settlemesh credits topup --credits 100 --json
+```
+
+## Hosted Agents
+
+Create from a built-in template and make it callable by other accounts:
+
+```bash
+settlemesh agents templates --json
+settlemesh agents create \
+  --name research-helper \
+  --template hermes \
+  --public \
+  --max-budget 50 \
+  --allowed-capabilities web.search,web.scrape,llm.chat \
+  --json
+settlemesh agents invoke agent_... --input '{"prompt":"Find three primary sources."}' --json
+```
+
+You can share the returned `agent_id`; other users can call public agents directly by id with `settlemesh agents invoke` or `settlemesh tool call agent.invoke`.
+
+## Managed Backends
+
+Create a SettleMesh project with database + app auth:
+
+```bash
+settlemesh projects create --name demo --db sqlite --auth email_password,magic_link
+settlemesh db query proj_... --sql "select 1"
+settlemesh db migrate proj_... --file schema.sql
+settlemesh db connection proj_...
+settlemesh auth users proj_...
+```
+
+`settlemesh db connection` is redacted by default. Add `--reveal` only in a trusted terminal. Database SQL endpoints accept a developer key or the one-time project server key returned by `projects create`; browser/public project keys are only for app auth.
+
+## Full-stack Apps, App APIs, and CLI Commands
+
+Deploy a local app project with SettleMesh auth, database, runtime API keys, and optional payment bindings:
+
+```bash
+./node_modules/.bin/settlemesh deploy ./my-next-app --name my-next-app --full-stack --wait --json
+```
+
+Expose selected routes from that app as APIs and CLI commands:
+
+```bash
+settlemesh apps api publish app_... --file app-api.json --json
+settlemesh apps api call app_... summarize --input '{"topic":"shipping"}' --json
+settlemesh apps commands publish app_... --file app-commands.json --json
+settlemesh run app:app_....summarize --input '{"topic":"shipping"}' --open --json
+```
+
+When a command has a web binding, `--open` can return a short-lived URL that opens the app in the browser using the caller's Settle login, without a second manual login.
+
+## Local Worker Offers
+
+Share a local OpenAI-compatible endpoint as a callable service:
+
+```bash
+settlemesh search "lend local compute worker offer"
+settlemesh worker start --name local-model --public --model local/model --endpoint http://localhost:11434/v1/chat/completions --credits-per-second 0.05
+settlemesh worker-offers list --json
+```
+
+## Public Tool Surface
+
+The public CLI surface includes discovery, tools, full-stack app deployment, App APIs/commands, hosted agents, local worker offers, credits, files, and managed project/database/auth operations. Provider-specific operations may still be gated on a given deployment. Inspect each tool's `availability`, `policy`, and `input_schema` before side-effecting or costly calls.

package/bin/settle.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pkg = require(path.join(__dirname, "..", "package.json"));
+const binaryOverride = process.env.SETTLEKIT_CLI_BINARY;
+const binaryName = process.platform === "win32" ? "settle.exe" : "settle";
+const binaryPath = binaryOverride || path.join(__dirname, "..", "vendor", binaryName);
+const commandName = path.basename(process.argv[1] || "settlemesh").replace(/\.cmd$/i, "");
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(`${commandName}: CLI binary was not found.`);
+  console.error("Run `npm rebuild -g settlemesh` or reinstall with `npm install -g settlemesh`.");
+  if (process.env.SETTLEKIT_CLI_RELEASE_BASE || process.env.SETTLEKIT_CLI_RELEASE_TAG) {
+    console.error("Check SETTLEKIT_CLI_RELEASE_BASE and SETTLEKIT_CLI_RELEASE_TAG.");
+  }
+  process.exit(1);
+}
+
+maybeWarnForStalePackage();
+
+const env = {
+  ...process.env,
+  SETTLEKIT_NPM_PACKAGE_VERSION: process.env.SETTLEKIT_NPM_PACKAGE_VERSION || pkg.version,
+  SETTLEKIT_NPM_PACKAGE_ROOT: process.env.SETTLEKIT_NPM_PACKAGE_ROOT || path.join(__dirname, ".."),
+  SETTLE_CLI_NAME: process.env.SETTLE_CLI_NAME || commandName,
+};
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env,
+});
+
+if (result.error) {
+  console.error(`${commandName}: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);
+
+function maybeWarnForStalePackage() {
+  if (process.env.SETTLEKIT_SKIP_VERSION_CHECK === "1") {
+    return;
+  }
+  const command = process.argv[2] || "";
+  const shouldCheck = new Set(["deploy", "recipes", "quickstart", "doctor", "version", "--version", "-v"]);
+  if (!shouldCheck.has(command)) {
+    return;
+  }
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const result = spawnSync(npm, ["view", pkg.name || "settlemesh", "version", "--silent"], {
+    encoding: "utf8",
+    timeout: 2500,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.error || result.status !== 0) {
+    return;
+  }
+  const latest = String(result.stdout || "").trim().split(/\s+/)[0];
+  if (!latest || compareVersions(pkg.version, latest) >= 0) {
+    return;
+  }
+  console.error(`${commandName}: warning: npm package ${pkg.name}@${pkg.version} is older than latest ${latest}.`);
+  console.error(`${commandName}: for agent/bootstrap flows, run \`npm install settlemesh@latest --prefer-online\` and use \`./node_modules/.bin/settlemesh\`.`);
+}
+
+function compareVersions(left, right) {
+  const a = String(left || "").split(".").map((part) => parseInt(part, 10) || 0);
+  const b = String(right || "").split(".").map((part) => parseInt(part, 10) || 0);
+  const n = Math.max(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return 0;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "settlemesh",
+  "version": "0.1.34",
+  "description": "SettleMesh CLI for services, models, apps, agents, workers, and credits",
+  "license": "UNLICENSED",
+  "homepage": "https://settlemesh.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CalLeeLQY/SettleKit.git",
+    "directory": "npm/settlekit"
+  },
+  "bugs": {
+    "url": "https://github.com/CalLeeLQY/SettleKit/issues"
+  },
+  "keywords": [
+    "settlemesh",
+    "settlekit",
+    "cli",
+    "agent",
+    "ai",
+    "tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kit": "bin/settle.js",
+    "settle": "bin/settle.js",
+    "settlemesh": "bin/settle.js",
+    "settlekit": "bin/settle.js"
+  },
+  "scripts": {
+    "prepack": "node scripts/stage-binaries.js",
+    "postpack": "node scripts/clean-staged-binaries.js",
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "vendor/",
+    "README.md"
+  ],
+  "config": {
+    "release_base": "https://github.com/CalLeeLQY/SettleKit/releases/download"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/clean-staged-binaries.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const vendorDir = path.resolve(__dirname, "..", "vendor");
+const assets = [
+  "settle-darwin-arm64",
+  "settle-darwin-x64",
+  "settle-linux-arm64",
+  "settle-linux-x64",
+  "settle-win32-arm64.exe",
+  "settle-win32-x64.exe",
+];
+
+for (const asset of assets) {
+  fs.rmSync(path.join(vendorDir, asset), { force: true });
+  fs.rmSync(path.join(vendorDir, `${asset}.sha256`), { force: true });
+}
+
+try {
+  if (fs.existsSync(vendorDir) && fs.readdirSync(vendorDir).length === 0) {
+    fs.rmdirSync(vendorDir);
+  }
+} catch {
+  // Best-effort cleanup only.
+}

package/scripts/install.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const http = require("node:http");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { fileURLToPath } = require("node:url");
+
+const root = path.resolve(__dirname, "..");
+const pkg = require(path.join(root, "package.json"));
+
+if (process.env.SETTLEKIT_SKIP_BINARY_INSTALL === "1") {
+  console.log("settlemesh: skipping binary install because SETTLEKIT_SKIP_BINARY_INSTALL=1");
+  process.exit(0);
+}
+
+const platform = platformName(process.platform);
+const arch = archName(process.arch);
+const binaryName = process.platform === "win32" ? "settle.exe" : "settle";
+const assetName = process.platform === "win32" ? `settle-${platform}-${arch}.exe` : `settle-${platform}-${arch}`;
+const vendorDir = path.join(root, "vendor");
+const target = path.join(vendorDir, binaryName);
+const bundledAsset = path.join(vendorDir, assetName);
+const bundledChecksum = `${bundledAsset}.sha256`;
+const tmp = path.join(os.tmpdir(), `settle-${process.pid}-${Date.now()}`);
+const checksumTmp = `${tmp}.sha256`;
+const releaseBase = stripTrailingSlash(
+    process.env.SETTLEKIT_CLI_RELEASE_BASE ||
+    process.env.npm_package_config_release_base ||
+    pkg.config?.release_base ||
+    "https://github.com/CalLeeLQY/SettleKit/releases/download",
+);
+const releaseTag = process.env.SETTLEKIT_CLI_RELEASE_TAG || `v${pkg.version}`;
+const url = `${releaseBase}/${releaseTag}/${assetName}`;
+const checksumURL = `${url}.sha256`;
+
+fs.mkdirSync(vendorDir, { recursive: true });
+
+if (fs.existsSync(bundledAsset)) {
+  try {
+    installFromLocalAsset(bundledAsset, bundledChecksum, target);
+    console.log(`settlemesh: installed bundled ${assetName}`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`settlemesh: bundled ${assetName} failed verification`);
+    console.error(`settlemesh: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+download(url, tmp, 0, (err) => {
+  if (err) {
+    console.error(`settlemesh: failed to download ${assetName}`);
+    console.error(`settlemesh: ${err.message}`);
+    console.error(`settlemesh: attempted ${url}`);
+    console.error("settlemesh: set SETTLEKIT_CLI_RELEASE_BASE or SETTLEKIT_CLI_RELEASE_TAG for private/staging releases.");
+    process.exit(1);
+  }
+  download(checksumURL, checksumTmp, 0, (checksumErr) => {
+    if (checksumErr && process.env.SETTLEKIT_SKIP_CHECKSUM !== "1") {
+      fs.rmSync(tmp, { force: true });
+      fs.rmSync(checksumTmp, { force: true });
+      console.error(`settlemesh: failed to download checksum for ${assetName}`);
+      console.error(`settlemesh: ${checksumErr.message}`);
+      console.error(`settlemesh: attempted ${checksumURL}`);
+      console.error("settlemesh: set SETTLEKIT_SKIP_CHECKSUM=1 only for trusted private test releases.");
+      process.exit(1);
+    }
+    if (!checksumErr && process.env.SETTLEKIT_SKIP_CHECKSUM !== "1") {
+      const expected = parseChecksum(fs.readFileSync(checksumTmp, "utf8"));
+      const actual = sha256File(tmp);
+      if (!expected || expected !== actual) {
+        fs.rmSync(tmp, { force: true });
+        fs.rmSync(checksumTmp, { force: true });
+        console.error(`settlemesh: checksum mismatch for ${assetName}`);
+        console.error(`settlemesh: expected ${expected || "(missing checksum)"}`);
+        console.error(`settlemesh: actual   ${actual}`);
+        process.exit(1);
+      }
+    }
+    fs.copyFileSync(tmp, target);
+    fs.rmSync(tmp, { force: true });
+    fs.rmSync(checksumTmp, { force: true });
+    if (process.platform !== "win32") {
+      fs.chmodSync(target, 0o755);
+    }
+    console.log(`settlemesh: installed ${assetName}`);
+  });
+});
+
+function installFromLocalAsset(source, checksumPath, destination) {
+  if (process.env.SETTLEKIT_SKIP_CHECKSUM !== "1") {
+    if (!fs.existsSync(checksumPath)) {
+      throw new Error(`missing checksum ${path.basename(checksumPath)}`);
+    }
+    const expected = parseChecksum(fs.readFileSync(checksumPath, "utf8"));
+    const actual = sha256File(source);
+    if (!expected || expected !== actual) {
+      throw new Error(`checksum mismatch: expected ${expected || "(missing checksum)"}, actual ${actual}`);
+    }
+  }
+  fs.copyFileSync(source, destination);
+  if (process.platform !== "win32") {
+    fs.chmodSync(destination, 0o755);
+  }
+}
+
+function parseChecksum(value) {
+  const match = String(value || "").match(/[a-fA-F0-9]{64}/);
+  return match ? match[0].toLowerCase() : "";
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  const data = fs.readFileSync(filePath);
+  hash.update(data);
+  return hash.digest("hex");
+}
+
+function platformName(value) {
+  switch (value) {
+    case "darwin":
+    case "linux":
+    case "win32":
+      return value;
+    default:
+      throw new Error(`unsupported platform ${value}`);
+  }
+}
+
+function archName(value) {
+  switch (value) {
+    case "x64":
+    case "arm64":
+      return value;
+    default:
+      throw new Error(`unsupported architecture ${value}`);
+  }
+}
+
+function stripTrailingSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+function download(rawURL, destination, redirectCount, done) {
+  if (redirectCount > 5) {
+    done(new Error("too many redirects"));
+    return;
+  }
+  let parsed;
+  try {
+    parsed = new URL(rawURL);
+  } catch (err) {
+    done(err);
+    return;
+  }
+  if (parsed.protocol === "file:") {
+    try {
+      fs.copyFileSync(fileURLToPath(parsed), destination);
+      done();
+    } catch (err) {
+      done(err);
+    }
+    return;
+  }
+  const client = parsed.protocol === "http:" ? http : https;
+  const request = client.get(rawURL, (response) => {
+    const status = response.statusCode || 0;
+    const location = response.headers.location;
+    if (status >= 300 && status < 400 && location) {
+      response.resume();
+      download(new URL(location, rawURL).toString(), destination, redirectCount + 1, done);
+      return;
+    }
+    if (status !== 200) {
+      response.resume();
+      done(new Error(`HTTP ${status}`));
+      return;
+    }
+    const file = fs.createWriteStream(destination, { mode: 0o755 });
+    response.pipe(file);
+    file.on("finish", () => file.close(done));
+    file.on("error", done);
+  });
+  request.on("error", done);
+  request.setTimeout(120000, () => request.destroy(new Error("download timed out")));
+}

package/scripts/stage-binaries.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..", "..", "..");
+const pkgRoot = path.resolve(__dirname, "..");
+const distDir = path.join(root, "dist");
+const vendorDir = path.join(pkgRoot, "vendor");
+const assets = [
+  "settle-darwin-arm64",
+  "settle-darwin-x64",
+  "settle-linux-arm64",
+  "settle-linux-x64",
+  "settle-win32-arm64.exe",
+  "settle-win32-x64.exe",
+];
+
+if (process.env.SETTLEKIT_SKIP_VENDOR_STAGE === "1") {
+  console.log("settlemesh: skipping bundled binary staging because SETTLEKIT_SKIP_VENDOR_STAGE=1");
+  process.exit(0);
+}
+
+if (!fs.existsSync(distDir)) {
+  console.warn("settlemesh: dist/ was not found; npm package will rely on release download fallback");
+  process.exit(0);
+}
+
+fs.mkdirSync(vendorDir, { recursive: true });
+cleanupVendor();
+
+for (const asset of assets) {
+  const source = path.join(distDir, asset);
+  const checksum = `${source}.sha256`;
+  if (!fs.existsSync(source) || !fs.existsSync(checksum)) {
+    throw new Error(`missing release asset or checksum for ${asset}; run make cli-release first`);
+  }
+  fs.copyFileSync(source, path.join(vendorDir, asset));
+  fs.copyFileSync(checksum, path.join(vendorDir, `${asset}.sha256`));
+}
+
+console.log(`settlemesh: staged ${assets.length} bundled CLI binaries`);
+
+function cleanupVendor() {
+  for (const asset of assets) {
+    fs.rmSync(path.join(vendorDir, asset), { force: true });
+    fs.rmSync(path.join(vendorDir, `${asset}.sha256`), { force: true });
+  }
+}

package/vendor/settle-darwin-arm64.sha256

@@ -0,0 +1 @@
+1033476dad68da250fc04a53b6326d6ff4a8fa7a784c037087e12b1e7fd17736

package/vendor/settle-darwin-x64.sha256

@@ -0,0 +1 @@
+c2485074a305314022001f47539836c0c9683fea74752ef945dec74a8553bbfe

package/vendor/settle-linux-arm64.sha256

@@ -0,0 +1 @@
+6983bdd99ed0b9dd12cecff5e514a3b56d83489f5ce5635944254063680f4311

package/vendor/settle-linux-x64.sha256

@@ -0,0 +1 @@
+1284edd5a9d437970f0b60c7d05c3a76e8091061668d7daea7dc7ebb1da35dc5

package/vendor/settle-win32-arm64.exe.sha256

@@ -0,0 +1 @@
+4d31f80b34a44dcff12f42b0b153c740c0d41082f5b8bc54fa083837f9e17e86

package/vendor/settle-win32-x64.exe.sha256

@@ -0,0 +1 @@
+de63eaaf0c9edde24ab4607ab167a7733ee43e6f9940cb1fbbfdb516ddd2aede