@backifydev/cli 0.2.2 → 0.3.1

package/README.md

@@ -1,12 +1,15 @@
 # @backifydev/cli
 
-Set up and check a Backify application repository.
+Set up, connect, record requests, and ship a Backify application repository. CLI 0.3.0 adds the connected AI delivery workflow.
 
 ```sh
 npx @backifydev/cli init --app app_xxxxx
 npx @backifydev/cli doctor
 npx @backifydev/cli sync
 npx @backifydev/cli login
+npx @backifydev/cli status
+npx @backifydev/cli report --check
+npx @backifydev/cli ship
 ```
 
 `login` opens the Backify portal in your browser. Sign in and select an organization; the portal returns the organization and access token to the CLI through a random, short-lived callback bound to `127.0.0.1`. The CLI stores them in `~/.backify.json`. Set `portalUrl` in that file to use another portal, or `BACKIFY_PORTAL_URL` in the environment. `login <token> [organizationId]` remains available for scripted development.
@@ -18,3 +21,11 @@ The app configuration stores `instructionVersion`, matching the version declared
 You can start from an empty folder without a Git repository. `init` creates a minimal private `package.json` before installing the SDK, without choosing a framework. Add the application's framework and development/build scripts afterward. Existing manifests are preserved; in a non-empty application or monorepo, run `init` from the appropriate JavaScript/TypeScript package directory.
 
 See the [agent setup guide](https://agent.backify.dev/).
+
+Copy the application AI prompt in Backify to receive an application-scoped, single-use pairing command. Codes expire after 15 minutes; redeemed sessions expire after seven days. Add `--clone` to the connection command only in an empty directory. Credentials are stored in the user's home configuration, not the project. The default API is `https://api.backify.dev/api`; local development can override it with `BACKIFY_API_URL` or the copied command's `--api` option. HTTPS is required outside loopback.
+
+`init` adds a persistent delivery guide linked from the existing agent instructions. Before each application-building request, the agent sends only the user's own text through stdin to `backify prompt record --stdin --id <UUID>`, optionally adding repeated `--filename <basename>` arguments. Reuse the UUID on retries. The command never reads attachments; their bodies, extracted text, full paths, setup/pairing prompts, and credentials must not be submitted. History is displayed oldest-first under the application. This is an explicit agent workflow, not an automatic interceptor for every coding tool.
+
+`ship` runs configured checks, verifies the repository/branch, and pushes already-committed source using a short-lived repository-scoped GitHub App credential. It never stages, commits, force-pushes, or fabricates preview testing. It waits for the exact healthy preview, then publishes when policy and permissions allow. Required testing/approval returns a pending state and preview URL, not a false successful production deployment. Use `--preview-only` to stop at preview, or `--timeout <seconds>` to change the default 1200-second wait. Applications must currently be at the repository root; Backify Cloud needs static index.html output, and customer Azure needs a Dockerfile serving port 8080.
+
+`disconnect` revokes that user's application CLI sessions. `logout` removes local credentials only. Prompt histories and local reports remain subject to application permissions. Deploy the matching API and publish CLI 0.3.0 before enabling this flow in production.

package/dist/index.js

@@ -1,20 +1,73 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, rmSync } from "node:fs";
-import { homedir } from "node:os";
-import { join as join2 } from "node:path";
-import { randomBytes } from "node:crypto";
-import { createServer } from "node:http";
-import { spawn } from "node:child_process";
+// src/development.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync3, renameSync, rmSync } from "node:fs";
+import { join as join3, resolve as resolve2 } from "node:path";
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { randomUUID } from "node:crypto";
 
 // src/setup.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync, readdirSync } from "node:fs";
+import { basename, dirname, join as join2, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 
+// ../platform/dist/delivery.js
+var deliveryInstructions = `# Backify application delivery and prompt history
+
+Instruction version: 3
+Versioned guide: https://agent.backify.dev/v3/delivery.md
+
+These instructions are for AI coding tools building applications on Backify, not the Backify platform implementation. Complete the application and deliver a verified deployment, not just SDK setup. Respect the coding tool's own permissions and confirmation settings; preserve unrelated work and applicable repository instructions.
+
+## Connect and initialize
+
+Use the connection command from the copied Backify prompt. The application ID, organization, API address, and single-use pairing code are already supplied there; never invent them. Pairing expires after 15 minutes. Never record the code or setup prompt in project files, Git, prompt history, or logs. The CLI stores an application-scoped session outside the repository. If access expires, obtain a new setup prompt or use CLI browser login.
+
+Inspect the workspace before connecting. In an empty project folder, add --clone to the supplied connect command to clone the connected repository without a separate GitHub login. In an existing repository, verify it matches the connected repository and branch; never overwrite unrelated files or force-push. Do not clone into a non-empty folder.
+
+Run the initialization command supplied in the prompt. Read the installed AGENTS.md and BACKIFY-WORKFLOW.md before changing application code. Initialization installs this workflow alongside the persistent SDK instructions. Follow https://agent.backify.dev/v3 for instruction version 3; use the guide matching backify.json in an existing application. Do not silently upgrade its managed instruction version or overwrite instructions outside the managed block.
+
+Run the following to discover the connected hosting target, repository, branch, reports, releases, and deployment failures:
+
+    npx @backifydev/cli@0.3.0 status
+
+Connection and initialization may proceed without application requirements. Then ask what to build if none were supplied; never invent requirements or record this setup text as a user requirement.
+
+## Record each user request
+
+For EVERY user request to build or modify this application, including the initial requirements supplied alongside or after setup, record only the user's own requirement text before changing application code. Submit the text through standard input to:
+
+    npx @backifydev/cli@0.3.0 prompt record --stdin --id <new-UUID> [--filename <basename> ...]
+
+Record requests separately and in order. Generate a new UUID per request and reuse that UUID on retries. Add one --filename argument per attachment, using only its basename. Never send attachment bodies, extracted text, images, full paths, assistant responses, tool output, secrets, connection commands, or this setup/pairing block. Filename arguments are metadata only; never read attachment bodies to submit them. If recording fails, retry or report the blocker; never silently claim a request was recorded.
+
+## Build for the connected hosting target
+
+Inspect the framework, lockfile, scripts, configuration, and applicable repository instructions before editing. Preserve the existing framework. Use @backifydev/sdk for platform capabilities, verify API signatures against its installed types and https://docs.backify.dev/capabilities/, and do not directly provision external infrastructure.
+
+For Backify Cloud, build a static application with a build script and index.html in its output. For customer Azure, provide a working repository-root Dockerfile whose HTTP server listens on 0.0.0.0:8080. Backify handles deployment to the existing authorized target; neither application code nor the coding tool should provision cloud infrastructure.
+
+Do not claim unsupported hosted server functions or SDK execution paths work. Report unsupported runtime requirements instead of substituting another platform. Keep secrets server-side and out of browser code, project files, and Git.
+
+## Verify, push, and publish
+
+Run:
+
+    npx @backifydev/cli@0.3.0 report --check
+
+Fix relevant failures, then commit only application changes for this request using a meaningful message. Never commit credentials or unrelated user changes. Then run:
+
+    npx @backifydev/cli@0.3.0 ship
+
+The CLI verifies the repository and branch, runs checks, pushes committed source using a short-lived repository-scoped credential, waits for the exact source's healthy preview, and publishes through existing Backify permissions and policy. It never stages or commits files, force-pushes, changes hosting, fabricates preview testing, or bypasses approval. Use --preview-only only when the user requests a preview.
+
+If testing or approval is required, return the preview URL and explain the remaining action. Otherwise return the verified production URL and actual check results only after healthy activation. Inspect failures with the status command, fix them, and retry without asking the user to perform routine deployment steps. Never invent a successful check or deployment.
+
+These instructions are an explicit agent workflow, not a universal chat interceptor. Request capture depends on the coding tool following this guide or an integration invoking the recording command.
+`;
+
 // ../platform/dist/index.js
-var INSTRUCTION_VERSION = 2;
+var INSTRUCTION_VERSION = 3;
 var SDK_PACKAGE = "@backifydev/sdk";
 var DOCS_URL = "https://docs.backify.dev";
 var capability = (name, imp, description, stateful = false, provisioner = name) => ({ name, import: imp, version: 1, stateful, provisioner, docs: `${DOCS_URL}/capabilities/${name}`, description, destructiveRemovalRequiresApproval: stateful });
@@ -70,6 +123,10 @@ Require explicit confirmation before destructive data operations or removing sta
 Inspect the framework, lockfile, scripts, configuration, and applicable repository instructions before editing. Preserve the existing framework and unrelated work. Implement the requested application rather than stopping at SDK setup; ask what to build if requirements are missing.
 Run relevant tests, typechecking, lint, and builds using the repository's scripts when available. Report changes, checks, and remaining blockers accurately; do not claim unverified success.
 
+## Connected application delivery
+
+For connected applications, follow \`BACKIFY-WORKFLOW.md\` and https://agent.backify.dev/v${INSTRUCTION_VERSION}/delivery.md before changing application code. Record every user build or modification request, including initial requirements, with attachment filenames only; never submit attachment contents or setup credentials. Verify checks and publish through the connected CLI workflow without bypassing testing, approval, or coding-tool permissions. Report only verified deployment URLs.
+
 ## Instruction maintenance
 
 The authoritative documentation is ${DOCS_URL}/. The root at https://agent.backify.dev/ always shows the latest guide; use the versioned guide above for this repository's installed instructions.
@@ -122,38 +179,64 @@ function validateConfig(value) {
 }
 var BACKIFY_SCHEMA = { $schema: "https://json-schema.org/draft/2020-12/schema", $id: `${DOCS_URL}/schema/backify.json`, type: "object", additionalProperties: false, required: ["$schema", "platform", "sdk", "appId", "instructionVersion", "docs", "instructions"], properties: { $schema: { const: `${DOCS_URL}/schema/backify.json` }, platform: { const: "backify" }, sdk: { const: SDK_PACKAGE }, appId: { type: "string", pattern: "^app_[A-Za-z0-9_-]+$" }, instructionVersion: { type: "integer", minimum: 1 }, docs: { type: "string", format: "uri" }, instructions: { type: "object", additionalProperties: false, required: ["preferBackifyCapabilities", "allowDirectCloudInfrastructure"], properties: { preferBackifyCapabilities: { const: true }, allowDirectCloudInfrastructure: { const: false } } } } };
 
+// src/delivery.ts
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+var previousGeneratedWorkflowHashes = /* @__PURE__ */ new Set(["6eb280ae7bdb14c390011686c41400f59c023304c3015d8440b7e80aaafa1c11", "545e03a1d5b996ade179e0e60ed5c86accdadc1982c1c25efd094e34f72f47ee"]);
+function validateDeliveryInstructions(root) {
+  const path = join(root, "BACKIFY-WORKFLOW.md");
+  if (existsSync(path)) {
+    const existing = readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+    if (existing !== deliveryInstructions && !previousGeneratedWorkflowHashes.has(createHash("sha256").update(existing).digest("hex"))) throw new Error("BACKIFY-WORKFLOW.md contains different instructions. Review it before initializing; it will not be overwritten.");
+  }
+}
+function installDeliveryInstructions(root, instructionFiles2) {
+  validateDeliveryInstructions(root);
+  const path = join(root, "BACKIFY-WORKFLOW.md");
+  writeFileSync(path, deliveryInstructions);
+  for (const relative of instructionFiles2) {
+    const instructionPath = join(root, relative), content = readFileSync(instructionPath, "utf8");
+    if (content.includes("## Backify delivery")) continue;
+    const link = relative.startsWith(".github") ? "../BACKIFY-WORKFLOW.md" : "BACKIFY-WORKFLOW.md";
+    writeFileSync(instructionPath, content.trimEnd() + "\n\n## Backify delivery\n\nFor application delivery and recording each user request, follow [BACKIFY-WORKFLOW.md](" + link + ").\n");
+  }
+}
+
 // src/setup.ts
-var instructionFiles = ["AGENTS.md", "CLAUDE.md", join(".github", "copilot-instructions.md")];
+var instructionFiles = ["AGENTS.md", "CLAUDE.md", join2(".github", "copilot-instructions.md")];
 function detectPackageManager(root = process.cwd()) {
-  for (const [file, name] of [["pnpm-lock.yaml", "pnpm"], ["yarn.lock", "yarn"], ["bun.lockb", "bun"], ["bun.lock", "bun"], ["package-lock.json", "npm"]]) if (existsSync(join(root, file))) return name;
+  for (const [file, name] of [["pnpm-lock.yaml", "pnpm"], ["yarn.lock", "yarn"], ["bun.lockb", "bun"], ["bun.lock", "bun"], ["package-lock.json", "npm"]]) if (existsSync2(join2(root, file))) return name;
   return "npm";
 }
 function updateInstructions(root = process.cwd()) {
   const updates = instructionFiles.map((relative) => {
-    const path = join(root, relative);
-    return { path, content: updateManagedInstructions(existsSync(path) ? readFileSync(path, "utf8") : "") };
+    const path = join2(root, relative);
+    return { path, content: updateManagedInstructions(existsSync2(path) ? readFileSync2(path, "utf8") : "") };
   });
   for (const { path, content } of updates) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content);
+    writeFileSync2(path, content);
   }
 }
 function synchronize(root = process.cwd()) {
-  const path = join(root, "backify.json");
-  if (!existsSync(path)) throw new Error("backify.json is missing; run backify init --app app_xxxxx");
-  const value = JSON.parse(readFileSync(path, "utf8")), issues = validateConfig(value);
+  const path = join2(root, "backify.json");
+  if (!existsSync2(path)) throw new Error("backify.json is missing; run backify init --app app_xxxxx");
+  const value = JSON.parse(readFileSync2(path, "utf8")), issues = validateConfig(value);
   if (issues.length) throw new Error(issues.join("; "));
   if (value.instructionVersion > INSTRUCTION_VERSION) throw new Error("This app uses newer instructions. Install a matching or newer CLI before syncing.");
+  validateDeliveryInstructions(root);
   updateInstructions(root);
+  installDeliveryInstructions(root, instructionFiles);
   value.instructionVersion = INSTRUCTION_VERSION;
-  writeFileSync(path, JSON.stringify(value, null, 2) + "\n");
+  writeFileSync2(path, JSON.stringify(value, null, 2) + "\n");
 }
 function writeConfig(appId, root = process.cwd()) {
-  writeFileSync(join(root, "backify.json"), JSON.stringify(createConfig(appId), null, 2) + "\n");
+  writeFileSync2(join2(root, "backify.json"), JSON.stringify(createConfig(appId), null, 2) + "\n");
 }
 function sdkInstalled(root = process.cwd()) {
   try {
-    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
     return Boolean(pkg.dependencies?.[SDK_PACKAGE] || pkg.devDependencies?.[SDK_PACKAGE]);
   } catch {
     return false;
@@ -165,12 +248,12 @@ function installSdk(root = process.cwd()) {
   if (result.status !== 0) throw new Error(`Could not install ${SDK_PACKAGE} with ${manager}`);
 }
 function ensurePackageManifest(root) {
-  const path = join(root, "package.json");
-  if (existsSync(path)) return;
+  const path = join2(root, "package.json");
+  if (existsSync2(path)) return;
   const setupFiles = /* @__PURE__ */ new Set([".git", ".gitignore", ".github", "AGENTS.md", "CLAUDE.md", "README.md", "LICENSE", "backify.json"]);
   if (readdirSync(root).some((file) => !setupFiles.has(file))) throw new Error("package.json is missing. Run backify init from the existing application's JavaScript/TypeScript package directory, or start in an empty folder. See https://agent.backify.dev/");
   const name = basename(resolve(root)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "backify-app";
-  writeFileSync(path, JSON.stringify({ name, version: "0.0.0", private: true, type: "module" }, null, 2) + "\n", { flag: "wx" });
+  writeFileSync2(path, JSON.stringify({ name, version: "0.0.0", private: true, type: "module" }, null, 2) + "\n", { flag: "wx" });
 }
 function initialize(appId, root = process.cwd(), install = true) {
   if (!/^app_[A-Za-z0-9_-]+$/.test(appId)) throw new Error("Provide an application ID using --app app_xxxxx");
@@ -178,43 +261,247 @@ function initialize(appId, root = process.cwd(), install = true) {
   if (install) installSdk(root);
   writeConfig(appId, root);
   updateInstructions(root);
+  installDeliveryInstructions(root, instructionFiles);
 }
 function doctor(root = process.cwd()) {
   const issues = [], warnings = [];
   if (!sdkInstalled(root)) issues.push(`${SDK_PACKAGE} is not installed`);
   let config;
   try {
-    config = JSON.parse(readFileSync(join(root, "backify.json"), "utf8"));
+    config = JSON.parse(readFileSync2(join2(root, "backify.json"), "utf8"));
     issues.push(...validateConfig(config));
   } catch {
     issues.push("backify.json is missing or invalid JSON");
   }
   if (config && config.instructionVersion !== INSTRUCTION_VERSION) issues.push(`Repository instruction version ${config.instructionVersion}; CLI version ${INSTRUCTION_VERSION}. Use the matching CLI or run backify sync to upgrade.`);
   for (const relative of instructionFiles) {
-    const path = join(root, relative);
-    if (!existsSync(path)) {
+    const path = join2(root, relative);
+    if (!existsSync2(path)) {
       issues.push(`${relative} is missing`);
       continue;
     }
-    issues.push(...managedInstructionIssues(readFileSync(path, "utf8")).map((issue) => `${relative} ${issue}`));
+    issues.push(...managedInstructionIssues(readFileSync2(path, "utf8")).map((issue) => `${relative} ${issue}`));
   }
   let version = "unknown";
   try {
-    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
     version = pkg.dependencies?.[SDK_PACKAGE] ?? pkg.devDependencies?.[SDK_PACKAGE] ?? "missing";
   } catch {
   }
   return { valid: issues.length === 0, appId: config?.appId, sdkVersion: version, instructionVersion: config?.instructionVersion, currentInstructionVersion: INSTRUCTION_VERSION, issues, warnings };
 }
 
+// src/development.ts
+function applicationGuid(appId) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(appId)) return appId.toLowerCase();
+  const match = /^app_([0-9a-f]{32})$/i.exec(appId);
+  if (!match) throw new Error("Use the application ID supplied by Backify.");
+  const value = match[1];
+  return [value.slice(0, 8), value.slice(8, 12), value.slice(12, 16), value.slice(16, 20), value.slice(20)].join("-");
+}
+function projectApplication(root = process.cwd()) {
+  if (!existsSync3(join3(root, "backify.json"))) throw new Error("Run backify connect --app <application-id>, then backify init.");
+  return JSON.parse(readFileSync3(join3(root, "backify.json"), "utf8")).appId;
+}
+function apiAddress(value) {
+  const address = new URL(value);
+  if (address.username || address.password || address.search || address.hash || address.protocol !== "https:" && !(address.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(address.hostname))) throw new Error("Backify API must use HTTPS (HTTP is allowed only on loopback for local development).");
+  return address.toString().replace(/\/$/, "");
+}
+function apiClient(session, transport = fetch) {
+  const base = apiAddress(session.apiUrl);
+  return async (path, init) => {
+    if (!path.startsWith("/") || path.startsWith("//")) throw new Error("Invalid API path.");
+    if (session.expiresAt && Date.parse(session.expiresAt) <= Date.now()) throw new Error("CLI session expired. Copy a new setup prompt or run backify login.");
+    const response = await transport(base + path, { ...init, redirect: "error", signal: AbortSignal.timeout(3e4), headers: { "content-type": "application/json", "X-Organization-ID": session.organizationId, ...session.token ? { authorization: "Bearer " + session.token } : {}, ...init?.headers } });
+    if (!response.ok) {
+      let message = "Backify request failed (" + response.status + ").";
+      try {
+        const problem = await response.json();
+        message = [problem.code, problem.title].filter(Boolean).join(": ") || message;
+      } catch {
+      }
+      throw new Error(message);
+    }
+    return response.status === 204 ? void 0 : await response.json();
+  };
+}
+function saveUserConfig(path, config) {
+  const temporary = path + "." + randomUUID() + ".tmp";
+  try {
+    writeFileSync3(temporary, JSON.stringify(config, null, 2) + "\n", { mode: 384, flag: "wx" });
+    if (process.platform === "win32") {
+      const account = [process.env.USERDOMAIN, process.env.USERNAME].filter(Boolean).join("\\");
+      if (!account) throw new Error("Cannot identify the account to protect CLI credentials.");
+      const secured = spawnSync2("icacls", [temporary, "/inheritance:r", "/grant:r", account + ":(F)"], { windowsHide: true, encoding: "utf8" });
+      if (secured.status !== 0) throw new Error("Could not restrict CLI credential file permissions.");
+    }
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+function repositoryName(remote) {
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i.exec(remote);
+  if (!match) throw new Error("Repository must be a credential-free GitHub URL.");
+  return match[1].toLowerCase();
+}
+function git(args2, root = process.cwd(), environment = process.env) {
+  const result = spawnSync2("git", args2, { cwd: root, env: environment, encoding: "utf8", windowsHide: true, maxBuffer: 2 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error("Git " + args2[0] + " failed. Check repository access, branch protection, and local changes.");
+  return result.stdout.trim();
+}
+function gitEnvironment(repository, token) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) throw new Error("Invalid repository.");
+  return { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_COUNT: "3", GIT_CONFIG_KEY_0: "http.https://github.com/" + repository + ".git.extraheader", GIT_CONFIG_VALUE_0: "Authorization: Basic " + Buffer.from("x-access-token:" + token).toString("base64"), GIT_CONFIG_KEY_1: "credential.helper", GIT_CONFIG_VALUE_1: "", GIT_CONFIG_KEY_2: "http.followRedirects", GIT_CONFIG_VALUE_2: "false" };
+}
+async function cloneProject(call2, appId, root = process.cwd()) {
+  const status = await call2("/apps/" + applicationGuid(appId) + "/developer");
+  if (!status.repository || !status.branch || !status.workflowReady) throw new Error("Connect the repository in Backify and wait for workflow setup.");
+  if (readdirSync2(root).length) throw new Error("--clone requires an empty directory. Existing files are never overwritten.");
+  const credential = await call2("/apps/" + applicationGuid(appId) + "/developer/git-credential", { method: "POST" });
+  if (credential.repository.toLowerCase() !== status.repository.toLowerCase()) throw new Error("Repository changed. Run connect again.");
+  git(["clone", "--single-branch", "--branch", status.branch, "--", "https://github.com/" + status.repository + ".git", "."], root, gitEnvironment(status.repository, credential.token));
+}
+async function readPrompt(input) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of input) {
+    const bytes = Buffer.from(chunk);
+    size += bytes.length;
+    if (size > 128e3) throw new Error("Prompt exceeds the size limit.");
+    chunks.push(bytes);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text.trim() || text.length > 32e3) throw new Error("Provide between 1 and 32000 characters of user prompt text.");
+  if (/\bbfcli_[0-9a-f]{64}\b|--pair\s+[0-9a-f]{64}/i.test(text)) throw new Error("Do not record setup prompts or Backify credentials.");
+  return text;
+}
+function attachmentNames(values) {
+  if (values.length > 50) throw new Error("At most 50 attachment filenames are allowed.");
+  return [...new Set(values.map((value) => {
+    const filename = value.replace(/\\/g, "/").split("/").pop();
+    if (!filename || filename === "." || filename === ".." || filename.length > 255 || /[\x00-\x1f\x7f]/.test(filename)) throw new Error("Invalid attachment filename.");
+    return filename;
+  }))];
+}
+function localReport(runChecks, root = process.cwd()) {
+  const pkg = JSON.parse(readFileSync3(join3(root, "package.json"), "utf8"));
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  const framework = ["next", "vite", "astro", "@sveltejs/kit", "nuxt", "react", "express"].find((name) => dependencies[name]) ?? "unknown";
+  const setup = doctor(root);
+  const checks = [{ name: "backify doctor", status: setup.valid ? "passed" : "failed" }];
+  const manager = detectPackageManager(root);
+  for (const name of ["typecheck", "lint", "test", "build"]) {
+    if (!pkg.scripts?.[name]) continue;
+    const result = runChecks ? spawnSync2(manager, ["run", name], { cwd: root, stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, CI: "true" }, shell: process.platform === "win32", windowsHide: true, timeout: 10 * 6e4 }) : void 0;
+    checks.push({ name, status: result ? result.status === 0 ? "passed" : "failed" : "not-run" });
+  }
+  let branch = null, commitSha = null, dirty = true;
+  try {
+    branch = git(["branch", "--show-current"], root);
+    commitSha = git(["rev-parse", "HEAD"], root);
+    dirty = Boolean(git(["status", "--porcelain"], root));
+  } catch {
+  }
+  const outputDirectory = ["dist", "build", "out", "."].find((directory) => existsSync3(join3(root, directory, "index.html"))) ?? null;
+  return { framework, sdkVersion: dependencies["@backifydev/sdk"] ?? null, branch, commitSha, dirty, buildCommand: pkg.scripts?.build ? manager + " run build" : null, outputDirectory, hasDockerfile: existsSync3(join3(root, "Dockerfile")), checks };
+}
+function matchesSource(release, commit) {
+  return release?.commitSha === commit || release?.sourceCommitSha === commit;
+}
+async function waitForPreview(call2, prefix, commit, options = {}) {
+  const deadline = Date.now() + (options.timeoutMs ?? 20 * 6e4);
+  const sleep = options.sleep ?? ((delay) => new Promise((resolve3) => setTimeout(resolve3, delay)));
+  do {
+    const deployments = await call2(prefix + "/deployments");
+    const matching = deployments.find((release) => release.kind === "preview" && matchesSource(release, commit) && !options.previousDeploymentIds?.includes(release.id));
+    if (matching?.status === "failed") throw new Error("Deployment of this source failed. Run backify status and inspect its deployment steps.");
+    const overview = await call2(prefix + "/releases");
+    if (matchesSource(overview.preview, commit) && overview.preview?.status === "succeeded" && overview.preview.healthResult === "healthy") return overview;
+    const build = await call2(prefix + "/developer/build?commitSha=" + commit);
+    if ((options.previousBuildRunId === void 0 || build.runId !== options.previousBuildRunId) && ["failure", "cancelled", "timed_out", "action_required", "startup_failure"].includes(build.conclusion ?? "")) throw new Error("GitHub build " + build.conclusion + ". " + (build.url ?? "Run backify status for details."));
+    await sleep(options.intervalMs ?? 4e3);
+  } while (Date.now() < deadline);
+  throw new Error("Timed out waiting for this commit's healthy preview. Run backify status; no production release was requested.");
+}
+async function ship(call2, appId, options = {}) {
+  const root = options.root ?? process.cwd(), prefix = "/apps/" + applicationGuid(appId);
+  const status = await call2(prefix + "/developer");
+  if (!status.repository || !status.branch || !status.workflowReady) throw new Error("The application's repository and build workflow must be connected in Backify.");
+  if (!doctor(root).valid) throw new Error("Run backify doctor and fix project setup before shipping.");
+  if (applicationGuid(projectApplication(root)) !== applicationGuid(appId)) throw new Error("Local application ID does not match the application being shipped.");
+  const actualRoot = git(["rev-parse", "--show-toplevel"], root);
+  if (resolve2(actualRoot).toLowerCase() !== resolve2(root).toLowerCase()) throw new Error("Shipping currently requires the application at the repository root.");
+  const origin = git(["remote", "get-url", "origin"], root);
+  const pushOrigin = git(["remote", "get-url", "--push", "origin"], root);
+  if (repositoryName(origin) !== status.repository.toLowerCase() || repositoryName(pushOrigin) !== status.repository.toLowerCase()) throw new Error("Local repository does not match this Backify application.");
+  if (git(["branch", "--show-current"], root) !== status.branch) throw new Error("Use the connected branch: " + status.branch);
+  if (git(["status", "--porcelain"], root)) throw new Error("Commit application changes before shipping. The CLI never stages or commits unrelated files.");
+  const commit = git(["rev-parse", "HEAD"], root);
+  const report = localReport(true, root);
+  await call2(prefix + "/developer/report", { method: "POST", body: JSON.stringify(report) });
+  if (report.checks.some((check) => check.status === "failed")) throw new Error("Checks failed; nothing was pushed.");
+  if (status.hostingTargetType === "backify-cloud" && !report.outputDirectory) throw new Error("Backify Cloud requires a static build containing index.html.");
+  if (status.hostingTargetType === "azure" && !report.hasDockerfile) throw new Error("Customer Azure requires a repository-root Dockerfile.");
+  if (git(["status", "--porcelain"], root) || git(["rev-parse", "HEAD"], root) !== commit) throw new Error("Checks changed tracked source. Review and commit those changes before shipping.");
+  const previousDeployments = await call2(prefix + "/deployments");
+  const previousBuild = await call2(prefix + "/developer/build?commitSha=" + commit);
+  const credential = await call2(prefix + "/developer/git-credential", { method: "POST" });
+  if (credential.repository.toLowerCase() !== status.repository.toLowerCase()) throw new Error("Repository changed; reconnect before shipping.");
+  const environment = gitEnvironment(status.repository, credential.token);
+  const destination = "https://github.com/" + status.repository + ".git";
+  const remoteHead = git(["ls-remote", "--", destination, "refs/heads/" + status.branch], root, environment).split(/\s+/)[0];
+  git(["push", "--", destination, commit + ":refs/heads/" + status.branch], root, environment);
+  if (remoteHead === commit && !(matchesSource(status.releases.preview, commit) && status.releases.preview?.status === "succeeded")) await call2(prefix + "/deployments/preview", { method: "POST", body: JSON.stringify({ sourceRevision: "latest" }) });
+  const overview = await waitForPreview(call2, prefix, commit, { timeoutMs: options.timeoutMs, previousDeploymentIds: previousDeployments.map((deployment) => deployment.id), previousBuildRunId: previousBuild.runId ?? null });
+  if (overview.preview.commitSha !== commit) {
+    if (git(["status", "--porcelain"], root) || git(["rev-parse", "HEAD"], root) !== commit) throw new Error("Local work changed while the preview built. Review it before synchronizing the build commit.");
+    const refreshed = await call2(prefix + "/developer/git-credential", { method: "POST" });
+    if (refreshed.repository.toLowerCase() !== status.repository.toLowerCase()) throw new Error("Repository changed while building.");
+    git(["fetch", "--", destination, "refs/heads/" + status.branch], root, gitEnvironment(status.repository, refreshed.token));
+    git(["merge", "--ff-only", overview.preview.commitSha], root);
+  }
+  return publishPreview(call2, prefix, overview, options);
+}
+async function publishPreview(call2, prefix, overview, options = {}) {
+  if (!overview.preview || overview.preview.status !== "succeeded" || overview.preview.healthResult !== "healthy") throw new Error("Only a verified healthy preview can be published.");
+  const preview = overview.preview;
+  if (options.previewOnly) return { status: "preview-ready", url: preview.url };
+  if (overview.policy.requirePreviewTesting && !preview.testedAt) return { status: "testing-required", url: preview.url };
+  if (overview.live?.previewDeploymentId === preview.id && overview.live.status === "succeeded") return { status: "live", url: overview.live.url };
+  const promotion = await call2(prefix + "/deployments/promote", { method: "POST", headers: { "Idempotency-Key": "cli-ship-" + preview.id }, body: JSON.stringify({ previewDeploymentId: preview.id, tested: false }) });
+  if (promotion.status === "awaiting-approval" || promotion.approvalId) return { status: "awaiting-approval", url: preview.url };
+  if (!promotion.operationId) throw new Error("Publication returned no operation to verify. Run backify status.");
+  const deadline = Date.now() + (options.timeoutMs ?? 20 * 6e4);
+  do {
+    const operation = await call2("/operations/" + promotion.operationId);
+    if (operation.status === "failed" || operation.status === "cancelled") throw new Error(operation.errorMessage ?? "Production deployment did not complete.");
+    if (operation.status === "succeeded") {
+      const releases = await call2(prefix + "/releases");
+      if (releases.live?.previewDeploymentId !== preview.id || releases.live.status !== "succeeded" || releases.live.healthResult !== "healthy") throw new Error("Production did not activate this healthy release. Run backify status.");
+      return { status: "live", url: releases.live.url };
+    }
+    await new Promise((resolve3) => setTimeout(resolve3, 4e3));
+  } while (Date.now() < deadline);
+  throw new Error("Publication is still pending. Run backify status; deployment success has not been verified.");
+}
+
 // src/index.ts
-var configPath = join2(homedir(), ".backify.json");
-var userConfig = existsSync2(configPath) ? JSON.parse(readFileSync2(configPath, "utf8")) : { apiUrl: process.env.BACKIFY_API_URL ?? "http://localhost:5080/api" };
+import { readFileSync as readFileSync4, existsSync as existsSync4, rmSync as rmSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join4 } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+var configPath = join4(homedir(), ".backify.json");
+var userConfig = existsSync4(configPath) ? JSON.parse(readFileSync4(configPath, "utf8")) : {};
 var [command, ...args] = process.argv.slice(2);
 async function call(path, init) {
-  const response = await fetch(userConfig.apiUrl + path, { ...init, headers: { "content-type": "application/json", "X-Organization-ID": userConfig.organizationId ?? "", ...userConfig.token ? { authorization: `Bearer ${userConfig.token}` } : {} } });
-  if (!response.ok) throw new Error(await response.text());
-  return response.status === 204 ? {} : response.json();
+  let appId = option("--app");
+  if (!appId && existsSync4(join4(process.cwd(), "backify.json"))) appId = projectApplication();
+  const session = appId ? userConfig.sessions?.["app_" + applicationGuid(appId).replaceAll("-", "")] : void 0;
+  return apiClient(session ?? { token: userConfig.token ?? "", organizationId: userConfig.organizationId ?? "", apiUrl: process.env.BACKIFY_API_URL ?? userConfig.apiUrl ?? "https://api.backify.dev/api" })(path, init);
 }
 var option = (name) => {
   const index = args.indexOf(name);
@@ -246,7 +533,7 @@ async function browserLogin() {
         res.end("Backify CLI connected. You can close this tab.");
         userConfig.token = value.token;
         userConfig.organizationId = value.organizationId;
-        writeFileSync2(configPath, JSON.stringify(userConfig, null, 2));
+        saveUserConfig(configPath, userConfig);
         server.close();
         resolveLogin();
       } catch {
@@ -257,7 +544,7 @@ async function browserLogin() {
   });
   let resolveLogin = () => {
   };
-  const completed = new Promise((resolve2) => resolveLogin = resolve2);
+  const completed = new Promise((resolve3) => resolveLogin = resolve3);
   server.listen(0, "127.0.0.1", () => {
     const address = server.address();
     if (!address || typeof address === "string") throw new Error("Could not start local login callback");
@@ -284,20 +571,16 @@ async function browserLogin() {
 async function main() {
   switch (command) {
     case "init":
-      initialize(option("--app") ?? args.find((x) => !x.startsWith("-")) ?? "");
-      console.log("Backify initialized. SDK, configuration, and agent instructions are ready.");
+      initialize(option("--app") ?? args.find((value) => !value.startsWith("-")) ?? "");
+      console.log("Backify initialized. SDK, delivery instructions, and prompt history guidance are ready.");
       break;
-    case "sync": {
+    case "sync":
       synchronize();
-      console.log(`Backify instructions synchronized to version ${INSTRUCTION_VERSION}.`);
+      console.log("Backify instructions synchronized to version " + INSTRUCTION_VERSION);
       break;
-    }
     case "doctor": {
       const result = doctor();
-      console.log(`Backify doctor: ${result.valid ? "healthy" : "invalid"}`);
-      console.log(`App: ${result.appId ?? "missing"} \xB7 SDK: ${result.sdkVersion} \xB7 Instructions: ${result.instructionVersion ?? "missing"}/${result.currentInstructionVersion}`);
-      for (const warning of result.warnings) console.warn(`warning: ${warning}`);
-      for (const issue of result.issues) console.error(`error: ${issue}`);
+      console.log(JSON.stringify(result, null, 2));
       if (!result.valid) process.exitCode = 1;
       break;
     }
@@ -305,28 +588,98 @@ async function main() {
       if (args[0]) {
         userConfig.token = args[0];
         userConfig.organizationId = args[1] ?? userConfig.organizationId;
-        writeFileSync2(configPath, JSON.stringify(userConfig, null, 2));
-        console.log("Logged in to Backify");
-      } else {
+        saveUserConfig(configPath, userConfig);
+      } else await browserLogin();
+      console.log("Logged in to Backify");
+      break;
+    case "logout":
+      rmSync2(configPath, { force: true });
+      console.log("Local CLI credentials removed. Use disconnect before logout to revoke an application session.");
+      break;
+    case "connect": {
+      const appId = option("--app") ?? projectApplication(), key = "app_" + applicationGuid(appId).replaceAll("-", "");
+      const code = option("--pair"), organizationId = option("--organization") ?? userConfig.organizationId;
+      const address = apiAddress(option("--api") ?? process.env.BACKIFY_API_URL ?? userConfig.apiUrl ?? "https://api.backify.dev/api");
+      if (code) {
+        if (!organizationId) throw new Error("The setup prompt must supply the organization.");
+        const redeem = apiClient({ token: "", organizationId, apiUrl: address });
+        const paired = await redeem("/apps/" + applicationGuid(appId) + "/developer/pair", { method: "POST", body: JSON.stringify({ code }) });
+        userConfig.sessions ??= {};
+        userConfig.sessions[key] = { ...paired, apiUrl: address };
+        saveUserConfig(configPath, userConfig);
+      } else if (!userConfig.sessions?.[key] && !userConfig.token) {
         await browserLogin();
-        console.log("Logged in to Backify");
       }
-      ;
+      const session = userConfig.sessions?.[key] ?? { token: userConfig.token ?? "", organizationId: organizationId ?? userConfig.organizationId ?? "", apiUrl: address };
+      const client = apiClient(session);
+      await client("/apps/" + applicationGuid(appId) + "/developer");
+      userConfig.sessions ??= {};
+      userConfig.sessions[key] = session;
+      saveUserConfig(configPath, userConfig);
+      if (args.includes("--clone")) await cloneProject(client, appId);
+      console.log(JSON.stringify(await client("/apps/" + applicationGuid(appId) + "/developer"), null, 2));
       break;
-    case "logout":
-      rmSync(configPath, { force: true });
+    }
+    case "disconnect":
+      await call("/apps/" + applicationGuid(projectApplication()) + "/developer/session", { method: "DELETE" });
+      delete userConfig.sessions?.["app_" + applicationGuid(projectApplication()).replaceAll("-", "")];
+      saveUserConfig(configPath, userConfig);
+      console.log("Application CLI sessions revoked.");
       break;
+    case "status": {
+      const prefix = "/apps/" + applicationGuid(option("--app") ?? projectApplication());
+      console.log(JSON.stringify(await call(prefix + "/developer"), null, 2));
+      const deployments = await call(prefix + "/deployments");
+      const latest = deployments[0];
+      if (latest?.status === "failed") console.log(JSON.stringify(await call(prefix + "/deployments/" + latest.id), null, 2));
+      try {
+        const commit = git(["rev-parse", "HEAD"]);
+        console.log(JSON.stringify(await call(prefix + "/developer/build?commitSha=" + commit), null, 2));
+      } catch {
+        console.log("Build status is unavailable for the current local commit.");
+      }
+      break;
+    }
+    case "report": {
+      const report = localReport(args.includes("--check"));
+      await call("/apps/" + applicationGuid(projectApplication()) + "/developer/report", { method: "POST", body: JSON.stringify(report) });
+      console.log(JSON.stringify(report, null, 2));
+      if (report.checks.some((check) => check.status === "failed")) process.exitCode = 1;
+      break;
+    }
+    case "prompt": {
+      if (args[0] !== "record" || !args.includes("--stdin")) throw new Error("Use backify prompt record --stdin --id <UUID> [--filename <name> ...]. Only user text and filenames are sent.");
+      const id = option("--id");
+      if (!id || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) throw new Error("Provide a UUID with --id; reuse it when retrying this prompt.");
+      const filenames = attachmentNames(args.flatMap((value, index) => value === "--filename" ? [args[index + 1] ?? ""] : []));
+      const text = await readPrompt(process.stdin);
+      console.log(JSON.stringify(await call("/apps/" + applicationGuid(projectApplication()) + "/prompts", { method: "POST", body: JSON.stringify({ clientPromptId: id, text, filenames }) })));
+      break;
+    }
+    case "ship": {
+      const timeout = Number(option("--timeout") ?? "1200");
+      if (!Number.isFinite(timeout) || timeout < 1 || timeout > 7200) throw new Error("--timeout must be between 1 and 7200 seconds.");
+      console.log(JSON.stringify(await ship(call, projectApplication(), { previewOnly: args.includes("--preview-only"), timeoutMs: timeout * 1e3 }), null, 2));
+      break;
+    }
+    case "request": {
+      const workspaceId = option("--workspace"), name = option("--name"), slug = option("--slug"), description = option("--description"), configurationFile = option("--configuration");
+      if (!workspaceId || !name || !slug || !description) throw new Error("Use backify request --workspace <id> --name <name> --slug <slug> --description <purpose> [--configuration <json-file>]");
+      const configuration = configurationFile ? JSON.parse(readFileSync4(configurationFile, "utf8")) : void 0;
+      console.log(await call("/apps/requests", { method: "POST", body: JSON.stringify({ workspaceId, name, slug, description, configuration }) }));
+      break;
+    }
     case "apps":
       console.table(await call("/apps"));
       break;
     case "deploy":
-      console.log(await call(`/apps/${args[0]}/deployments/preview`, { method: "POST", body: JSON.stringify({ sourceRevision: args[1] ?? "local" }) }));
+      console.log(await call("/apps/" + applicationGuid(args[0]) + "/deployments/preview", { method: "POST", body: JSON.stringify({ sourceRevision: args[1] ?? "latest" }) }));
       break;
     default:
-      console.log("backify init --app app_xxxxx | sync | doctor | login | logout | apps | deploy");
+      console.log("backify connect | init | doctor | sync | login | logout | disconnect | status | report [--check] | prompt record --stdin --id <UUID> | ship [--preview-only] | request | apps | deploy");
   }
 }
 main().catch((error) => {
-  console.error(error instanceof Error ? error.message : error);
+  console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;
 });

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@backifydev/cli",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Command-line setup and diagnostics for Backify applications",
   "type": "module",
-  "bin": { "backify": "dist/index.js" },
-  "files": ["dist/index.js", "README.md"],
+  "bin": {
+    "backify": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md"
+  ],
   "scripts": {
     "prebuild": "npm run build --workspace @backify/platform",
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js",
@@ -14,11 +19,19 @@
     "pretest": "npm run build --workspace @backify/platform",
     "test": "vitest run"
   },
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/frejnorling/backify.git", "directory": "packages/cli" },
-  "homepage": "https://agent.backify.dev/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frejnorling/backify.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://agent.backify.dev/",
   "license": "MIT",
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "devDependencies": {
     "@backify/platform": "*",
     "@types/node": "^24.3.1",