@promte/app-upload 0.1.12 → 0.2.0

package/README.md

@@ -1,25 +1,38 @@
 # promte-app-upload
 
-CLI for uploading Promte app bundles.
+CLI for uploading Promte apps. On servers with managed builds it uploads the project source, and Promte checks and builds it. Older servers get the built `dist` folder.
 
 ## Quick start
 ```
-npx @promte/app-upload config
+npx @promte/app-upload login
+npx @promte/app-upload config --host https://app.promte.dk --workspaceId <id>
 npx @promte/app-upload push
 ```
 
 ## Commands
 ```
-npx @promte/app-upload config
-  - interactive setup for backend host/workspaceId/dist (stored in ./promte-app-upload.config.json)
-
-npx @promte/app-upload push [--host ...] [--workspaceId ...] [--dist ...] [--zip ...] [--token ...]
-  - uploads ./dist by default
-  - host is the workspace backend URL used for prepare/finalize
-  - assets upload to app.promte.dk (or backend-provided uploadHost)
-  - use --zip <file> to upload an existing zip
+npx @promte/app-upload login [--host ...] [--app-url ...] [--no-open]
+  - opens Promte in the browser; approve "CLI access" there
+  - the 30-day token is saved in ~/.config/promte/credentials.json (never in the project)
+
+npx @promte/app-upload logout [--host ...]
+
+npx @promte/app-upload config [--host ...] [--workspaceId ...] [--source ...] [--dist ...]
+  - saves host/workspaceId/source/dist in ./promte-app-upload.config.json (interactive without flags)
+
+npx @promte/app-upload push [--host ...] [--workspaceId ...] [--source ...] [--dist ...] [--zip ...] [--token ...]
+  - asks the server for its upload mode
+  - source mode: zips the project (default .) without node_modules, dist, .env files and other files the server rejects
+  - built mode: zips ./dist (must contain index.html)
+  - prints the release status; releases under review are published after approval
+
+npx @promte/app-upload status [--release <id>]
+  - shows the latest releases or one release
+
+npx @promte/app-upload skill [--dir ...]
+  - writes the Promte app skill for coding agents to .claude/skills/promte-app/ and .agents/skills/promte-app/
 ```
 
 Notes:
-- Tokens are never stored in the config file.
-- If no token is provided, the CLI will prompt for it.
+- Token order: `--token`, `PROMTE_TOKEN`, then the token saved by `login`.
+- Only workspace admins can upload releases.

package/bin/promte-app-upload.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import AdmZip from "adm-zip";
 import undici from "undici";
 import readline from "node:readline/promises";
@@ -11,20 +14,53 @@ const BlobCtor = globalThis.Blob || Blob;
 const DEFAULT_HOST = "https://app.promte.dk";
 const DEFAULT_UPLOAD_HOST = "https://app.promte.dk";
 const DEFAULT_DIST = "./dist";
+const DEFAULT_SOURCE = ".";
 const CONFIG_PATH = path.resolve(process.cwd(), "promte-app-upload.config.json");
+const CREDENTIALS_PATH = path.join(
+  process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+  "promte",
+  "credentials.json",
+);
+const SHARED_APP_HOST_API = "https://app.promte.dk/api";
+const SKILL_PATH = fileURLToPath(new URL("../skill/SKILL.md", import.meta.url));
+
+// Mirrors the server's source ZIP rules (self-hosting/app-governance/source-archive.ts):
+// these are rejected there, so they are left out here.
+const SOURCE_SKIP_DIRS = new Set([
+  "node_modules", "bower_components", ".git", ".hg", ".svn", ".promte-source",
+  ".cache", ".yarn", ".npm", ".pnpm-store", ".turbo", ".vite", ".parcel-cache", ".next", ".nuxt", ".output",
+  "dist", "build", "out", "coverage", "__pycache__", ".pytest_cache", ".mypy_cache", ".venv", "venv",
+  ".ssh", ".aws", ".azure", ".gcloud", ".kube", ".docker", "__macosx",
+  ".claude", ".agents", ".codex", ".cursor", ".idea", ".vscode",
+]);
+const SOURCE_SKIP_FILE =
+  /^(?:\.env(?:\..*)?|\.npmrc|\.pypirc|\.netrc|\.ds_store|\.yarnrc(?:\.yml)?|\.secrets?|credentials(?:\.[^.]+)?|secrets?\.(?:json|ya?ml|toml)|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|promte-app-upload\.config\.json|yarn\.lock|pnpm-lock\.yaml|vite\.config\.[cm]?[jt]s)$|\.(?:pem|key|p12|pfx|keystore|jks|zip|tar|tgz|gz|7z|rar|map|tsbuildinfo|log|pyc|o|so|dll|exe|class)$/i;
+const SOURCE_ZIP_MAX_BYTES = 20 * 1024 * 1024;
+const SOURCE_MAX_FILES = 2000;
 
 function usage() {
   console.log(
     [
       "Usage:",
-      "  promte-app-upload config",
-      "  promte-app-upload push [--host <url>] [--workspaceId <id>] [--dist <path>] [--zip <file>] [--token <token>]",
+      "  promte-app-upload login [--host <url>] [--app-url <url>] [--no-open]",
+      "  promte-app-upload logout [--host <url>]",
+      "  promte-app-upload config [--host <url>] [--workspaceId <id>] [--source <dir>] [--dist <dir>]",
+      "  promte-app-upload push [--host <url>] [--workspaceId <id>] [--source <dir>] [--dist <dir>] [--zip <file>] [--token <token>]",
+      "  promte-app-upload status [--host <url>] [--workspaceId <id>] [--release <id>]",
+      "  promte-app-upload skill [--dir <project dir>]",
+      "",
+      "push asks the server which upload mode it uses:",
+      "  source: zips the project source (--source, default .) and the server checks and builds it",
+      "  built:  zips the built output (--dist, default ./dist) on servers without managed builds",
+      "",
+      "Token: --token, then PROMTE_TOKEN, then the token saved by `login`.",
       "",
       "Defaults:",
       `  host (backend URL): ${DEFAULT_HOST}`,
-      `  upload host: ${DEFAULT_UPLOAD_HOST}`,
+      `  source: ${DEFAULT_SOURCE}`,
       `  dist: ${DEFAULT_DIST}`,
       `  config: ${CONFIG_PATH}`,
+      `  credentials: ${CREDENTIALS_PATH}`,
     ].join("\n"),
   );
 }
@@ -35,8 +71,13 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg.startsWith("--")) {
       const key = arg.slice(2);
-      args[key] = argv[i + 1];
-      i += 1;
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i += 1;
+      }
     } else {
       args._.push(arg);
     }
@@ -69,6 +110,7 @@ async function prompt(question, defaultValue = "") {
 }
 
 async function promptSecret(question) {
+  if (!process.stdin.isTTY) return "";
   process.stdout.write(`${question}: `);
   process.stdin.setRawMode(true);
   process.stdin.resume();
@@ -103,16 +145,250 @@ function assert(condition, message) {
   }
 }
 
-async function runConfig() {
+async function runConfig(args) {
   const current = loadConfig();
-  const host = await prompt("Backend host", current.host || DEFAULT_HOST);
-  const workspaceId = await prompt("Workspace ID", current.workspaceId || "");
-  const dist = await prompt("Dist path", current.dist || DEFAULT_DIST);
+  const interactive = process.stdin.isTTY && !args.workspaceId;
+  const ask = (question, key, fallback) =>
+    typeof args[key] === "string"
+      ? args[key]
+      : interactive
+        ? prompt(question, current[key] || fallback)
+        : current[key] || fallback;
+  const host = await ask("Backend host", "host", DEFAULT_HOST);
+  const workspaceId = await ask("Workspace ID", "workspaceId", "");
+  const source = await ask("Source path", "source", DEFAULT_SOURCE);
+  const dist = await ask("Dist path (servers without managed builds)", "dist", DEFAULT_DIST);
   assert(workspaceId, "workspaceId is required");
-  saveConfig({ host, workspaceId, dist });
+  saveConfig({ host, workspaceId, source, dist });
   console.log(`Saved config to ${CONFIG_PATH}`);
 }
 
+function hostKey(host) {
+  return new URL(host).origin;
+}
+
+function loadCredentials() {
+  try {
+    return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function saveCredentials(next) {
+  fs.mkdirSync(path.dirname(CREDENTIALS_PATH), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(next, null, 2), { mode: 0o600 });
+  fs.chmodSync(CREDENTIALS_PATH, 0o600);
+}
+
+function resolveHost(args) {
+  return args.host || loadConfig().host || DEFAULT_HOST;
+}
+
+async function resolveToken(args, host) {
+  if (typeof args.token === "string") return args.token;
+  if (process.env.PROMTE_TOKEN) return process.env.PROMTE_TOKEN;
+  const saved = loadCredentials()[hostKey(host)];
+  if (saved?.token) return saved.token;
+  const token = await promptSecret("Promte token");
+  assert(
+    token,
+    `Not signed in to ${hostKey(host)}. Run \`promte-app-upload login\` first, or set PROMTE_TOKEN.`,
+  );
+  return token;
+}
+
+function openInBrowser(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const commandArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(command, commandArgs, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // The printed link still works.
+  }
+}
+
+async function runLogin(args) {
+  const host = resolveHost(args);
+  const startRes = await undiciFetch(new URL("/api/extension-auth/start", host).toString(), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client: "cli",
+      ...(typeof args["app-url"] === "string" ? { platformBaseUrl: args["app-url"] } : {}),
+    }),
+  });
+  const started = await parseResponseBody(startRes);
+  if (!startRes.ok || !started.json?.flowId) {
+    console.error(`Could not start sign-in (${startRes.status}): ${started.text || "Unknown error"}`);
+    process.exit(1);
+  }
+  const { flowId, flowSecret, approveUrl, expiresAt } = started.json;
+  const interval = Math.max(1000, Number(started.json.pollIntervalMs) || 1500);
+
+  console.log("Open this link, sign in to Promte and approve CLI access:");
+  console.log(`\n  ${approveUrl}\n`);
+  if (!args["no-open"]) openInBrowser(approveUrl);
+  console.log("Waiting for approval…");
+
+  const statusUrl = new URL("/api/extension-auth/status", host);
+  statusUrl.searchParams.set("flowId", flowId);
+  statusUrl.searchParams.set("flowSecret", flowSecret);
+  while (Date.now() < Number(expiresAt || Date.now() + 10 * 60 * 1000)) {
+    await new Promise((resolve) => setTimeout(resolve, interval));
+    let statusRes;
+    try {
+      statusRes = await undiciFetch(statusUrl.toString());
+    } catch {
+      // Keep waiting through brief network or server restarts.
+      continue;
+    }
+    const status = await parseResponseBody(statusRes);
+    const state = status.json?.state;
+    if (state === "approved" && status.json?.token) {
+      const credentials = loadCredentials();
+      credentials[hostKey(host)] = {
+        token: status.json.token,
+        email: status.json.email || "",
+        savedAt: new Date().toISOString(),
+      };
+      saveCredentials(credentials);
+      console.log(`Signed in${status.json.email ? ` as ${status.json.email}` : ""} ✅`);
+      console.log(`Token saved to ${CREDENTIALS_PATH} (valid for 30 days).`);
+      return;
+    }
+    if (["denied", "expired", "consumed", "not_found"].includes(state) || (!statusRes.ok && statusRes.status !== 429)) {
+      const reason =
+        state === "denied"
+          ? "the request was denied"
+          : state === "not_found" || state === "expired" || state === "consumed"
+            ? "the request expired or was already used"
+            : status.text || statusRes.status;
+      console.error(`Sign-in did not complete: ${reason}. Run \`promte-app-upload login\` again.`);
+      process.exit(1);
+    }
+  }
+  console.error("Sign-in expired. Run login again.");
+  process.exit(1);
+}
+
+function runLogout(args) {
+  const host = resolveHost(args);
+  const credentials = loadCredentials();
+  delete credentials[hostKey(host)];
+  saveCredentials(credentials);
+  console.log(`Signed out of ${hostKey(host)}.`);
+}
+
+function runSkill(args) {
+  const projectDir = path.resolve(process.cwd(), typeof args.dir === "string" ? args.dir : ".");
+  const skill = fs.readFileSync(SKILL_PATH, "utf8");
+  for (const base of [".claude", ".agents"]) {
+    const target = path.join(projectDir, base, "skills", "promte-app", "SKILL.md");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, skill);
+    console.log(`Wrote ${path.relative(process.cwd(), target) || target}`);
+  }
+}
+
+function collectSourceFiles(root) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SOURCE_SKIP_DIRS.has(entry.name.toLowerCase())) walk(abs);
+      } else if (entry.isFile() && !SOURCE_SKIP_FILE.test(entry.name)) {
+        files.push(abs);
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+
+function hasRuntimeDependencies(root) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    return ["dependencies", "peerDependencies", "optionalDependencies"].some(
+      (field) => manifest?.[field] && Object.keys(manifest[field]).length > 0,
+    );
+  } catch {
+    // Keep the lockfile when package.json is missing or unreadable.
+    return true;
+  }
+}
+
+function zipSource(sourcePath) {
+  const abs = path.resolve(process.cwd(), sourcePath);
+  assert(fs.existsSync(abs) && fs.statSync(abs).isDirectory(), `Source folder not found: ${abs}`);
+  let files = collectSourceFiles(abs);
+  // The server only reads package-lock.json to pin runtime dependencies. Without
+  // any, it adds nothing, and its registry URLs can trip a strict origin review.
+  if (!hasRuntimeDependencies(abs)) {
+    files = files.filter((file) => path.relative(abs, file) !== "package-lock.json");
+  }
+  assert(files.length > 0, `No source files found in ${abs}`);
+  assert(
+    files.length <= SOURCE_MAX_FILES,
+    `The source has ${files.length} files; the server accepts at most ${SOURCE_MAX_FILES}.`,
+  );
+  const zip = new AdmZip();
+  for (const file of files) {
+    const rel = path.relative(abs, file).split(path.sep).join("/");
+    zip.addFile(rel, fs.readFileSync(file));
+  }
+  const buffer = zip.toBuffer();
+  assert(
+    buffer.length <= SOURCE_ZIP_MAX_BYTES,
+    `The source ZIP is ${(buffer.length / 1024 / 1024).toFixed(1)} MiB; the server accepts at most 20 MiB.`,
+  );
+  return { buffer, files: files.length };
+}
+
+async function getUploadMode(host, workspaceId, token) {
+  const url = new URL("/api/app-upload/capabilities", host);
+  url.searchParams.set("workspaceId", workspaceId);
+  const res = await undiciFetch(url.toString(), { headers: { Authorization: `Bearer ${token}` } });
+  // Older servers have no capabilities endpoint and only accept built ZIPs.
+  if (res.status === 404) return { uploadMode: "built", available: true };
+  const body = await parseResponseBody(res);
+  if (res.status === 401 || res.status === 403) {
+    console.error(
+      `Not allowed to upload to workspace ${workspaceId} (${res.status}). You must be a workspace admin with access to app releases. If your token expired, run \`promte-app-upload login\` again.`,
+    );
+    process.exit(1);
+  }
+  if (!res.ok || !body.json) {
+    console.error(`Could not read upload mode (${res.status}): ${body.text || "Unknown error"}`);
+    process.exit(1);
+  }
+  return body.json;
+}
+
+async function runStatus(args) {
+  const config = loadConfig();
+  const host = resolveHost(args);
+  const workspaceId = args.workspaceId || config.workspaceId;
+  assert(workspaceId, "workspaceId is required (config or --workspaceId)");
+  const token = await resolveToken(args, host);
+  const url = new URL(
+    `/api/app-upload/releases${typeof args.release === "string" ? `/${encodeURIComponent(args.release)}` : ""}`,
+    host,
+  );
+  url.searchParams.set("workspaceId", workspaceId);
+  const res = await undiciFetch(url.toString(), { headers: { Authorization: `Bearer ${token}` } });
+  const body = await parseResponseBody(res);
+  if (!res.ok) {
+    console.error(`Could not read releases (${res.status}): ${body.text || "Unknown error"}`);
+    process.exit(1);
+  }
+  console.log(JSON.stringify(body.json?.release ?? (body.json?.releases || []).slice(0, 5), null, 2));
+}
+
 function ensureDist(distPath) {
   const abs = path.resolve(process.cwd(), distPath);
   assert(fs.existsSync(abs), `Dist folder not found: ${abs}`);
@@ -184,11 +460,11 @@ async function parseResponseBody(res) {
 
 async function runPush(args) {
   const config = loadConfig();
-  const host = args.host || config.host || DEFAULT_HOST;
+  const host = resolveHost(args);
   const workspaceId = args.workspaceId || config.workspaceId;
   const dist = args.dist || config.dist || DEFAULT_DIST;
-  const zipPath = args.zip;
-  let token = args.token;
+  const sourcePath = args.source || config.source || DEFAULT_SOURCE;
+  const zipPath = typeof args.zip === "string" ? args.zip : null;
   const requestedVersion = args.version ? Number(args.version) : null;
   if (args.version) {
     assert(
@@ -198,29 +474,40 @@ async function runPush(args) {
   }
 
   assert(workspaceId, "workspaceId is required (config or --workspaceId)");
-  const absDist = zipPath ? null : ensureDist(dist);
+  const token = await resolveToken(args, host);
 
-  if (!token) {
-    token = await promptSecret("Workspace token");
+  const capabilities = await getUploadMode(host, workspaceId, token);
+  if (!capabilities.available) {
+    console.error(capabilities.reason || "The server cannot build apps right now. Try again later.");
+    process.exit(1);
   }
-  assert(token, "token is required");
+  const mode = capabilities.uploadMode === "source" ? "source" : "built";
 
   let zipBuffer;
-  let zipName = "dist.zip";
+  let zipName;
   if (zipPath) {
-    const { abs, name } = ensureZipHasIndex(zipPath);
+    if (mode === "built") ensureZipHasIndex(zipPath);
+    const abs = path.resolve(process.cwd(), zipPath);
+    assert(fs.existsSync(abs) && /\.zip$/i.test(abs), `Zip file not found: ${abs}`);
     zipBuffer = fs.readFileSync(abs);
-    zipName = name;
+    zipName = path.basename(abs);
+  } else if (mode === "source") {
+    const zipped = zipSource(sourcePath);
+    zipBuffer = zipped.buffer;
+    zipName = "source.zip";
+    console.log(`Zipped ${zipped.files} source files (${(zipBuffer.length / 1024).toFixed(0)} KiB).`);
   } else {
+    const absDist = ensureDist(dist);
     const zip = new AdmZip();
     zip.addLocalFolder(absDist, "");
     zipBuffer = zip.toBuffer();
+    zipName = "dist.zip";
   }
 
   assert(BlobCtor, "Blob is not available in this Node runtime.");
   const form = new FormData();
   const blob = new BlobCtor([zipBuffer], { type: "application/zip" });
-  form.append("app", blob, zipName);
+  form.append(mode === "source" ? "source" : "app", blob, zipName);
 
   const prepareUrl = new URL("/api/app-upload/prepare", host);
   const prepareRes = await undiciFetch(prepareUrl.toString(), {
@@ -251,8 +538,10 @@ async function runPush(args) {
 
   const uploadToken = prepareBody.json?.uploadToken;
   const version = Number(prepareBody.json?.version);
+  const preparedHost = String(prepareBody.json?.uploadHost || "").trim();
+  // "same-server" means the backend that prepared the upload also receives it.
   const uploadHost =
-    String(prepareBody.json?.uploadHost || "").trim() || DEFAULT_UPLOAD_HOST;
+    preparedHost === "same-server" ? host : preparedHost || DEFAULT_UPLOAD_HOST;
 
   assert(uploadToken, "Prepare response is missing uploadToken");
   assert(
@@ -260,6 +549,7 @@ async function runPush(args) {
     "Prepare response has invalid version",
   );
 
+  if (mode === "source") console.log(`Uploading version ${version}; the server checks and builds it…`);
   const uploadUrl = new URL("/api/upload-app", uploadHost);
   uploadUrl.searchParams.set("workspaceId", workspaceId);
   uploadUrl.searchParams.set("version", String(version));
@@ -301,12 +591,51 @@ async function runPush(args) {
     process.exit(1);
   }
 
+  // Same as the web app: published built releases on other servers are also
+  // copied to the shared app host that serves *.apps.promte.dk.
+  const hostname = new URL(host).hostname;
+  if (
+    mode === "built" &&
+    typeof finalizeBody.json?.hostedCopyToken === "string" &&
+    hostname !== "localhost" &&
+    hostname !== "127.0.0.1"
+  ) {
+    const copyUrl = new URL(`${SHARED_APP_HOST_API}/app-upload/hosted-copy`);
+    copyUrl.searchParams.set("workspaceId", workspaceId);
+    copyUrl.searchParams.set("version", String(version));
+    const copyForm = new FormData();
+    copyForm.append("app", new BlobCtor([zipBuffer], { type: "application/zip" }), zipName);
+    const copyRes = await undiciFetch(copyUrl.toString(), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${finalizeBody.json.hostedCopyToken}` },
+      body: copyForm,
+    });
+    if (!copyRes.ok) {
+      const copyBody = await parseResponseBody(copyRes);
+      console.error(
+        `The release was published but could not be copied to the app host (${copyRes.status}): ${copyBody.text || "Unknown error"}. Push again to retry.`,
+      );
+      process.exit(1);
+    }
+  }
+
+  const status = String(finalizeBody.json?.status || uploadBody.json?.status || "reviewing");
   console.log("Upload complete ✅");
   console.log(`Workspace: ${workspaceId}`);
   console.log(`Version:   ${version}`);
+  console.log(`Mode:      ${mode}`);
   if (uploadBody.json?.filesWritten != null) {
     console.log(`Files:     ${uploadBody.json.filesWritten}`);
   }
+  if (finalizeBody.json?.releaseId) console.log(`Release:   ${finalizeBody.json.releaseId}`);
+  console.log(`Status:    ${status}`);
+  if (status === "published") {
+    console.log("The release is published and active.");
+  } else {
+    console.log(
+      "The release is under review; the current app stays online until it is published. Check with `promte-app-upload status`.",
+    );
+  }
 }
 
 async function main() {
@@ -319,7 +648,27 @@ async function main() {
   }
 
   if (cmd === "config") {
-    await runConfig();
+    await runConfig(args);
+    return;
+  }
+
+  if (cmd === "login") {
+    await runLogin(args);
+    return;
+  }
+
+  if (cmd === "logout") {
+    runLogout(args);
+    return;
+  }
+
+  if (cmd === "status") {
+    await runStatus(args);
+    return;
+  }
+
+  if (cmd === "skill") {
+    runSkill(args);
     return;
   }
 

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "@promte/app-upload",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "CLI to upload Promte app bundles",
   "type": "module",
   "bin": {
     "promte-app-upload": "bin/promte-app-upload.js"
   },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.18.1"
   },
   "dependencies": {
-    "adm-zip": "^0.5.16",
+    "adm-zip": "^0.6.1",
     "undici": "^7.8.0"
   }
 }

package/skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: promte-app
+description: Build, test locally and publish Promte apps (React apps embedded in a Promte workspace) with @promte/app-library and the @promte/app-upload CLI. Use when creating or changing a Promte app, calling Promte models/data/knowledge/functions from an app, or uploading a new app release to Promte.
+---
+
+# Promte apps
+
+A Promte app is a small React single-page app that runs in an iframe inside a Promte workspace. It talks to Promte only through `@promte/app-library`, which gets a short-lived app token from the parent page. You write the source; **Promte checks and builds it on the server** when you upload it.
+
+Two npm packages:
+
+- `@promte/app-library` – React provider, hooks and a client for models, data, files, knowledge, functions and more.
+- `@promte/app-upload` – CLI that signs in, uploads the source and reports the release status.
+
+## Workflow
+
+1. Create or update the project so it follows the **build contract** below.
+2. Run it locally with Vite and preview it inside Promte (see *Local development*).
+3. Sign in once: `npx @promte/app-upload login`. The user approves in the browser; the token is stored in `~/.config/promte/credentials.json` for 30 days. Never ask the user to paste a token into chat.
+4. Save the target once: `npx @promte/app-upload config --host <backend URL> --workspaceId <id>` (writes `promte-app-upload.config.json`; it holds no secrets).
+5. Upload: `npx @promte/app-upload push`. Read the output: build errors come back as plain messages, fix them and push again.
+6. If the status is not `published`, the release is under review. Check with `npx @promte/app-upload status`. The current app stays online until a release is published.
+
+`login` and `push` need a person once: login needs browser approval, and only workspace admins may upload. For CI or a sandbox without a browser, set `PROMTE_TOKEN` instead.
+
+Default host is `https://app.promte.dk`. Customers on their own Promte server use that server's URL (the address they open Promte on). For a local backend use e.g. `--host http://localhost:3000` and, when the frontend runs on another port, `login --app-url http://localhost:5173`.
+
+## Build contract (source uploads)
+
+The server builds with a **fixed React + Vite configuration** (Node 22, ES2022, `base: './'`). Anything that needs a custom build step is rejected. Keep the project plain:
+
+```
+index.html            # optional; otherwise main.jsx/tsx/js/ts at root or in src/ is used
+src/main.jsx          # wraps the app in <PromteAppProvider>
+src/App.jsx
+src/*.css             # plain CSS (no Tailwind/PostCSS config)
+public/               # static files copied as-is
+functions/<name>/     # optional backend functions (private, never in the browser bundle)
+package.json
+package-lock.json     # required if you use ^ or ~ ranges
+```
+
+Rules the server enforces:
+
+- **No build config files:** `vite.config.*`, `postcss.config.*`, `tailwind.config.*`, `babel.config.*`, `webpack.config.*`, `rollup.config.*`, `.babelrc`, `.postcssrc`. The CLI leaves `vite.config.*` out of the upload so you can keep one for local dev only.
+- **tsconfig/jsconfig:** no `extends`, `paths`, `baseUrl`, `plugins`, `jsxImportSource` or decorators.
+- **package.json:** no `workspaces`, `imports`, `exports`, `overrides`, `resolutions`, `browser`, `babel`, `postcss`. No `preinstall`/`install`/`postinstall`/`prepare`/`prebuild`/`postbuild` scripts. `scripts.build` may only be `vite build` or `tsc && vite build` (it is not run anyway).
+- **Dependencies:** only `dependencies`/`peerDependencies`/`optionalDependencies` are installed (devDependencies are ignored, so put Vite and types there). Versions must be exact (`1.2.3`), or `^`/`~` pinned by `package-lock.json` (npm only; yarn/pnpm lockfiles are ignored). No tags, URLs, git refs or `npm:` aliases. At most 20 extra packages. Packages with native code or install scripts fail. A workspace may also require admin approval for each npm package ("npm package approval required").
+- **Supplied by Promte:** `react` and `react-dom` 19.2.8, `@promte/app-library` (whatever version that server has) and `html2canvas` 1.4.1. Put them in `devDependencies` so they are installed locally but not checked by the server. If you list them in `dependencies`, the version must match the server's exactly or by `^`/`~`, and the library version differs between servers. Never declare `vite`, `esbuild` or `scheduler` as dependencies.
+- **Source ZIP limits:** 20 MiB zipped, 50 MiB extracted, 10 MiB per file, 2,000 files. Text files must be UTF-8. Private keys, `.env*`, `.npmrc`, credentials, archives, source maps, `node_modules`, `dist` and `build` are rejected; the CLI skips them for you.
+- **Build output:** must contain `index.html`, at most 256 files and 6 MiB. No lint, typecheck or tests are run, so run them yourself before pushing.
+- Code under `functions/`, `backend/`, manifests and `.env` are private: importing them from browser code fails the build.
+- Build time is limited to roughly two minutes.
+
+### Minimal project
+
+`package.json`:
+
+```json
+{
+  "name": "my-promte-app",
+  "private": true,
+  "type": "module",
+  "scripts": { "dev": "vite", "build": "vite build" },
+  "dependencies": {},
+  "devDependencies": {
+    "@promte/app-library": "^0.1.6",
+    "@vitejs/plugin-react": "^4.3.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "vite": "^5.4.10"
+  }
+}
+```
+
+`vite.config.js` (local dev only; never uploaded):
+
+```js
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+export default defineConfig({ plugins: [react()], base: "./" });
+```
+
+`src/main.jsx`:
+
+```jsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { PromteAppProvider } from "@promte/app-library";
+import App from "./App.jsx";
+import "./style.css";
+
+createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <PromteAppProvider>
+      <App />
+    </PromteAppProvider>
+  </React.StrictMode>,
+);
+```
+
+Install with `npm install --legacy-peer-deps` (the library still declares a React 18 peer range) and commit `package-lock.json`.
+
+## Using @promte/app-library
+
+Everything must be inside `<PromteAppProvider>`. Wait for `ready` before calling the client; outside Promte the provider never becomes ready.
+
+```jsx
+import { usePromte, usePromteClient, usePromteUser, usePromteDarkMode, usePromteModels } from "@promte/app-library";
+
+const { ready, state, error } = usePromte();
+const client = usePromteClient();
+const user = usePromteUser();          // { email, isAdmin, role, workspaceId } | null
+const dark = usePromteDarkMode();      // follow Promte's theme
+const { models } = usePromteModels({ type: "llm", configuredOnly: true });
+```
+
+Client API (`client.…`):
+
+- **Models:** `models({ type, configuredOnly })` → `{ id, label, type, configured }[]`. Types: `llm`, `embedding`, `image`, `stt`, `tts`. Always pick a model from this list; never hard-code model IDs.
+- **Chat:** `chatText({ model, messages })` → string; `chatCompletions({ model, messages, temperature, reasoningEffort })` → OpenAI-style response. Messages: `{ role: "system"|"user"|"assistant", content }`.
+- **Embeddings:** `embeddings.create({ model, input })` → `{ data: [{ embedding }] }`.
+- **Data (JSON tree):** `data(scope).ref("a/b")` with `get()`, `set(v)`, `update({ "x/y": v })`, `remove()`, `push(v)`. Scope `"private"` (default, per user) or `"public"` (whole workspace; only admins can write). `get()` returns `null` if missing.
+- **Files** (newer servers): `files(scope)` with `upload(blob, { name })`, `list({ prefix })`, `download(id)`, `remove(id)`.
+- **Knowledge search:** `knowledge.search({ query, workspaceId?, maxResults?, generateSearchQuery? })` → `{ results: [{ title, text, sourceUrl }] }`.
+- **Web:** `web.scrapeUrl({ url })`.
+- **Audio:** `audio.tts(...)`, `audio.stt(...)`, `audio.voices()`.
+- **Guardrails:** `guardrails.check(value)` → `{ allowed, outcome: "allow"|"warn"|"block" }`.
+- **Backend functions:** `functions.invoke(name, input)` → the handler's result.
+
+The library's README on npm has the full reference and types.
+
+Rules:
+
+- Never put API keys, passwords or connection secrets in browser code. Credentials belong in admin-managed connections that backend functions use.
+- Store app state with `client.data()` or `client.files()` so it follows the user across devices, not `localStorage`.
+- Write user-facing text in the user's language. Promte apps are usually Danish; support both Danish and English when unsure.
+
+## Backend functions (optional)
+
+Each function is a folder `functions/<name>/` (lowercase letters, digits and hyphens, starting with a letter, max 64 characters, same as `name`) containing:
+
+- `function.json`: `name`, `description`, `triggers` (`{ "callable": true, "tool": false }`, optional `"schedule": { "cron": "0 7 * * 1-5", "timezone": "Europe/Copenhagen" }`), `inputSchema`, `outputSchema`, `connections` (connection IDs set up by an admin), `capabilities` (e.g. `"data.read"`, `"data.write"`).
+- `index.ts`: `export default async function (input, ctx) { … return json; }`.
+- Optional `tests.json`: `[{ "name", "input", "expected" }]`.
+
+Inside a handler you get `ctx.connections.request(id, { operation, params, body })`, `ctx.env.get(NAME)` and `ctx.data.get/set/update/delete(path, { scope })`. You may only import local `.ts`/`.js`/`.json` files under `functions/`; no npm or remote imports. Schemas use a small JSON Schema subset (`type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, min/max) with no `$ref`, `pattern` or unions. Defaults: 30 s, 128 MiB, 64 KiB input and 256 KiB output. Functions go through governance review with the release, and schedules must be activated by an admin after publishing.
+
+## Local development
+
+1. `npm run dev` (Vite on `http://localhost:5173`).
+2. In Promte, open the app's workspace → **Preview** → *Local development preview* (workspace admins only), and enter the local URL. Promte loads it in its iframe and hands it a token, so the library calls the real workspace.
+3. If the user cannot open Promte, you can still check that the app builds with `npx vite build`, but anything that needs `ready` will not run.
+
+## Troubleshooting
+
+| Message | Fix |
+| --- | --- |
+| `Not signed in` / 401 | Run `npx @promte/app-upload login`. |
+| 403 on upload | The user must be an admin of that workspace with access to app releases. |
+| `Custom build configuration is not supported` | Remove the build config file named in the error (the CLI already leaves out `vite.config.*`). |
+| `requires an exact npm version…` | Use an exact version, or keep `^`/`~` and commit `package-lock.json`. |
+| `is supplied by the fixed Coding runtime` | Move react/react-dom/@promte/app-library to `devDependencies`. |
+| `npm package approval required` | A workspace admin must approve that package and version. |
+| `Upload a clean source ZIP…` | A forbidden file slipped in; check the paths in the message. |
+| `The Azure source builder is unavailable` | Server-side problem; try again later or contact the Promte admin. |
+| Status `blocked` / `rejected` | Governance review found a problem; see the release in Promte → Releases. |
+| Blocked: `External origin … is not on the frontend allowlist` | The workspace only allows approved domains. Remove the URL from browser code, call it from a backend function, or ask an admin to allow it. (Older servers also flagged `package-lock.json`; the CLI leaves the lockfile out when there are no runtime `dependencies`.) |