@backifydev/cli 0.2.1 → 0.3.0

package/README.md

@@ -1,18 +1,31 @@
 # @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.
 
 `init` installs `@backifydev/sdk`, writes `backify.json`, and maintains the Backify blocks in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`. It preserves other instructions in those files.
 
+The app configuration stores `instructionVersion`, matching the version declared in each managed block and its immutable guide at `https://agent.backify.dev/v<number>`. The agent root always serves the latest guide as plain text. `doctor` detects version/content drift and malformed markers. Use `npx @backifydev/cli@latest sync` to explicitly upgrade all blocks and the configuration together; unrelated configuration and unmanaged instructions remain unchanged.
+
 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://docs.backify.dev/setup).
+
+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,18 @@
 #!/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/index.js
-var INSTRUCTION_VERSION = 1;
+var INSTRUCTION_VERSION = 2;
 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 });
@@ -41,25 +39,62 @@ function managedInstructions() {
 
 # Backify Platform Instructions
 
-This application runs on Backify.
+Instruction version: ${INSTRUCTION_VERSION}
+Versioned guide: https://agent.backify.dev/v${INSTRUCTION_VERSION}
+
+## Scope and platform policy
+
+This application runs on Backify. These rules govern application code targeting Backify, not the implementation of the Backify platform itself.
+Use \`@backifydev/sdk\` for platform capabilities. Do not directly integrate or provision cloud infrastructure, hosted authentication, databases, storage, queues, or schedulers when an equivalent Backify capability exists. If a capability is missing, explain the gap and ask before adding an external platform dependency.
+
+## SDK capability map
+
+- Authentication and authorization: \`auth\`.
+- Persistent data and files: \`db\` and \`storage\`.
+- Server functions: \`defineFunction\`; background work and schedules: \`jobs\` and \`jobs.schedule\`.
+- Events, outbound HTTP, and AI: \`events\`, \`http.fetch\`, and \`ai\`.
+- Server-side secrets, configuration, audit, and logs: \`secrets\`, \`config\`, \`audit\`, and \`logs\`.
+
+Verify API signatures against the installed SDK types and the relevant guide at ${DOCS_URL}/capabilities/. Never invent SDK methods. Use \`@backifydev/sdk/local\` for tests and local development; \`@backifydev/sdk/runtime\` is for runtime hosts, not application code.
 
-Use \`@backifydev/sdk\` for application platform capabilities. Prefer Backify for authentication, database, storage, server functions, background and scheduled jobs, events, secrets, AI, external HTTP access, audit logging, application logging, and configuration.
+## Security and data safety
 
-Do not directly provision or integrate Azure, AWS, GCP, Supabase, Firebase, Auth0, database hosting, object storage, queues, schedulers, or infrastructure-as-code when an equivalent Backify capability exists.
+Keep secrets server-side. Never commit or log credentials, expose secrets to browser code, or place cloud-management credentials in applications. Enforce authorization in trusted server code and scope data access to the authenticated user or organization as required.
+Scope cookies to the exact application hostname by omitting the \`Domain\` attribute. Never use a parent-domain cookie unless explicitly required.
+Require explicit confirmation before destructive data operations or removing stateful resources. Removing a capability declaration does not authorize deleting its data.
 
-The authoritative documentation is ${DOCS_URL}. If unsure, check it before adding an external platform dependency. Preserve all repository instructions outside this managed block.
+## Implementation workflow
+
+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.
+
+## 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.
+Keep \`backify.json\` \`instructionVersion\` aligned with this block. Run \`npx @backifydev/cli@latest doctor\` to check consistency and \`npx @backifydev/cli@latest sync\` to adopt a newer instruction version. Never silently upgrade instructions during an unrelated feature change.
+Preserve all content outside this managed block and all more-specific repository instructions.
 
 ${MANAGED_END}`;
 }
+function managedInstructionIssues(content) {
+  const normalized = content.replace(/\r\n/g, "\n"), starts = normalized.split(MANAGED_START).length - 1, ends = normalized.split(MANAGED_END).length - 1;
+  if (starts === 0 && ends === 0)
+    return ["does not contain Backify managed instructions"];
+  if (starts !== 1 || ends !== 1)
+    return ["contains duplicate or incomplete Backify managed markers"];
+  const start = normalized.indexOf(MANAGED_START), end = normalized.indexOf(MANAGED_END);
+  if (end < start)
+    return ["contains reversed Backify managed markers"];
+  return normalized.slice(start, end + MANAGED_END.length) === managedInstructions() ? [] : ["contains stale or inconsistent Backify managed instructions; run backify sync"];
+}
 function updateManagedInstructions(content) {
+  const issues = managedInstructionIssues(content);
+  if (issues.some((issue) => issue.includes("markers")))
+    throw new Error(issues.join("; "));
   const block = managedInstructions(), start = content.indexOf(MANAGED_START), end = content.indexOf(MANAGED_END);
-  if (start >= 0 && end >= start)
+  if (start >= 0)
     return content.slice(0, start) + block + content.slice(end + MANAGED_END.length);
-  return content.trim() ? `${content.trimEnd()}
-
-${block}
-` : `${block}
-`;
+  return content.trim() ? content.trimEnd() + "\n\n" + block + "\n" : block + "\n";
 }
 function createConfig(appId) {
   return { $schema: `${DOCS_URL}/schema/backify.json`, platform: "backify", sdk: SDK_PACKAGE, appId, instructionVersion: INSTRUCTION_VERSION, docs: DOCS_URL, instructions: { preferBackifyCapabilities: true, allowDirectCloudInfrastructure: false } };
@@ -85,25 +120,54 @@ 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";
+var deliveryInstructions = "# Backify delivery and prompt history\n\nFor EVERY subsequent user request to build or modify this application, record only the user's own request text before changing code through standard input to:\n\n    npx @backifydev/cli@0.3.0 prompt record --stdin --id <new-UUID> [--filename <basename> ...]\n\nRecord requests separately and in order. Reuse the UUID on retries. Never include setup instructions, pairing commands, assistant responses, tool output, attachment contents, extracted text, images, full paths, or credentials. Filename arguments are metadata only; never read attachment bodies to submit them. Retry and report recording failures instead of silently dropping prompts.\n\nUse npx @backifydev/cli@0.3.0 status to inspect hosting and repository readiness. Run npx @backifydev/cli@0.3.0 report --check, fix failures, and commit only application changes relevant to this request. Then run npx @backifydev/cli@0.3.0 ship. The CLI verifies the connected repository and branch, runs checks, pushes committed source with short-lived repository-scoped credentials, waits for its healthy preview, and requests policy-governed publication. It never stages or commits files, force-pushes, changes hosting, or fabricates preview testing.\n\nWhen testing or approval is required, return the preview URL and remaining action. Return a production URL only after healthy activation is verified. Respect the coding tool's permissions and preserve unrelated work. Use --preview-only only when the user requests a preview. Report unsupported hosted runtime requirements instead of substituting another platform.\n\nCredentials belong outside the project. Never store pairing codes or session tokens here or in Git. Expired access requires a new setup prompt or browser login. These instructions are an explicit agent workflow, not a universal chat interceptor.\n";
+function installDeliveryInstructions(root, instructionFiles2) {
+  const path = join(root, "BACKIFY-WORKFLOW.md");
+  if (existsSync(path) && readFileSync(path, "utf8") !== deliveryInstructions) throw new Error("BACKIFY-WORKFLOW.md contains different instructions. Review it before initializing; it will not be overwritten.");
+  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()) {
-  for (const relative of instructionFiles) {
-    const path = join(root, relative);
+  const updates = instructionFiles.map((relative) => {
+    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, updateManagedInstructions(existsSync(path) ? readFileSync(path, "utf8") : ""));
+    writeFileSync2(path, content);
   }
 }
+function synchronize(root = process.cwd()) {
+  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.");
+  updateInstructions(root);
+  value.instructionVersion = INSTRUCTION_VERSION;
+  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;
@@ -115,12 +179,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://docs.backify.dev/setup");
+  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");
@@ -128,44 +192,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?.instructionVersion < INSTRUCTION_VERSION) warnings.push(`Repository instruction version ${config.instructionVersion}; current version ${INSTRUCTION_VERSION}. Run backify sync.`);
+  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;
     }
-    const text = readFileSync(path, "utf8");
-    if (!text.includes(MANAGED_START) || !text.includes(MANAGED_END)) issues.push(`${relative} does not contain Backify managed instructions`);
+    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);
@@ -197,7 +464,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 {
@@ -208,7 +475,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");
@@ -235,25 +502,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": {
-      const path = join2(process.cwd(), "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"));
-      value.instructionVersion = INSTRUCTION_VERSION;
-      writeFileSync2(path, JSON.stringify(value, null, 2) + "\n");
-      updateInstructions();
-      console.log(`Backify instructions synchronized to version ${INSTRUCTION_VERSION}.`);
+    case "sync":
+      synchronize();
+      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;
     }
@@ -261,28 +519,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,6 +1,6 @@
 {
   "name": "@backifydev/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Command-line setup and diagnostics for Backify applications",
   "type": "module",
   "bin": { "backify": "dist/index.js" },
@@ -15,8 +15,8 @@
     "test": "vitest run"
   },
   "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/frejnorling/backify.git", "directory": "packages/cli" },
-  "homepage": "https://docs.backify.dev/setup",
+  "repository": { "type": "git", "url": "git+https://github.com/frejnorling/backify.git", "directory": "packages/cli" },
+  "homepage": "https://agent.backify.dev/",
   "license": "MIT",
   "engines": { "node": ">=20" },
   "devDependencies": {