@backifydev/cli 0.2.0 → 0.2.2

package/README.md

@@ -1,13 +1,20 @@
-# @backifydev/cli
-
-Set up and check a Backify application repository.
-
-```sh
-npx @backifydev/cli init --app app_xxxxx
+# @backifydev/cli
+
+Set up and check a Backify application repository.
+
+```sh
+npx @backifydev/cli init --app app_xxxxx
 npx @backifydev/cli doctor
 npx @backifydev/cli sync
+npx @backifydev/cli login
 ```
 
+`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.
 
-See the [agent setup guide](https://docs.backify.dev/setup).
+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://agent.backify.dev/).

package/dist/index.js

@@ -4,14 +4,17 @@
 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/setup.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { basename, dirname, join, 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 });
@@ -38,25 +41,62 @@ function managedInstructions() {
 
 # Backify Platform Instructions
 
-This application runs on Backify.
+Instruction version: ${INSTRUCTION_VERSION}
+Versioned guide: https://agent.backify.dev/v${INSTRUCTION_VERSION}
 
-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.
+## Scope and platform policy
 
-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.
+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.
 
-The authoritative documentation is ${DOCS_URL}. If unsure, check it before adding an external platform dependency. Preserve all repository instructions outside this managed block.
+## 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.
+
+## Security and data safety
+
+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.
+
+## 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 } };
@@ -89,12 +129,25 @@ function detectPackageManager(root = process.cwd()) {
   return "npm";
 }
 function updateInstructions(root = process.cwd()) {
-  for (const relative of instructionFiles) {
+  const updates = instructionFiles.map((relative) => {
     const path = join(root, relative);
+    return { path, content: updateManagedInstructions(existsSync(path) ? readFileSync(path, "utf8") : "") };
+  });
+  for (const { path, content } of updates) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, updateManagedInstructions(existsSync(path) ? readFileSync(path, "utf8") : ""));
+    writeFileSync(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);
+  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;
+  writeFileSync(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");
 }
@@ -111,9 +164,17 @@ function installSdk(root = process.cwd()) {
   const manager = detectPackageManager(root), args2 = manager === "npm" ? ["install", SDK_PACKAGE] : ["add", SDK_PACKAGE], result = spawnSync(manager, args2, { cwd: root, stdio: "inherit", shell: process.platform === "win32" });
   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 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" });
+}
 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");
-  if (!existsSync(join(root, "package.json"))) throw new Error("Run backify init in a JavaScript/TypeScript repository containing package.json");
+  ensurePackageManifest(root);
   if (install) installSdk(root);
   writeConfig(appId, root);
   updateInstructions(root);
@@ -128,15 +189,14 @@ function doctor(root = process.cwd()) {
   } 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)) {
       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(readFileSync(path, "utf8")).map((issue) => `${relative} ${issue}`));
   }
   let version = "unknown";
   try {
@@ -160,6 +220,67 @@ var option = (name) => {
   const index = args.indexOf(name);
   return index >= 0 ? args[index + 1] : void 0;
 };
+function openBrowser(url) {
+  const command2 = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open", args2 = process.platform === "win32" ? ["/c", "start", "", '"' + url + '"'] : [url];
+  const child = spawn(command2, args2, { stdio: "ignore", detached: true, shell: process.platform === "win32" });
+  child.unref();
+}
+async function browserLogin() {
+  const state = randomBytes(24).toString("base64url"), server = createServer((req, res) => {
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, { "access-control-allow-origin": "*", "access-control-allow-methods": "POST, OPTIONS", "access-control-allow-headers": "content-type" });
+      return res.end();
+    }
+    if (req.method !== "POST" || req.url !== "/callback") {
+      res.writeHead(404);
+      return res.end();
+    }
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (part) => raw += part);
+    req.on("end", () => {
+      try {
+        const value = JSON.parse(raw);
+        if (value.state !== state || typeof value.token !== "string" || typeof value.organizationId !== "string") throw new Error("Invalid callback");
+        res.writeHead(200, { "access-control-allow-origin": "*", "content-type": "text/plain" });
+        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));
+        server.close();
+        resolveLogin();
+      } catch {
+        res.writeHead(400, { "access-control-allow-origin": "*" });
+        res.end("Invalid or expired Backify CLI login.");
+      }
+    });
+  });
+  let resolveLogin = () => {
+  };
+  const completed = new Promise((resolve2) => resolveLogin = resolve2);
+  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");
+    const callback = `http://127.0.0.1:${address.port}/callback`;
+    const portal = new URL(process.env.BACKIFY_PORTAL_URL ?? userConfig.portalUrl ?? "https://backify.dev");
+    portal.searchParams.set("cli_callback", callback);
+    portal.searchParams.set("cli_state", state);
+    console.log(`Opening ${portal.origin} to sign in to Backify\u2026`);
+    openBrowser(portal.toString());
+  });
+  const timeout = setTimeout(() => {
+    server.close();
+    rejectLogin(new Error("Backify login timed out. Run backify login to try again."));
+  }, 5 * 6e4);
+  let rejectLogin = () => {
+  };
+  const failed = new Promise((_, reject) => rejectLogin = reject);
+  try {
+    await Promise.race([completed, failed]);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
 async function main() {
   switch (command) {
     case "init":
@@ -167,12 +288,7 @@ async function main() {
       console.log("Backify initialized. SDK, configuration, and agent instructions 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();
+      synchronize();
       console.log(`Backify instructions synchronized to version ${INSTRUCTION_VERSION}.`);
       break;
     }
@@ -186,10 +302,16 @@ async function main() {
       break;
     }
     case "login":
-      userConfig.token = args[0] ?? "development";
-      userConfig.organizationId = args[1] ?? userConfig.organizationId;
-      writeFileSync2(configPath, JSON.stringify(userConfig, null, 2));
-      console.log("Logged in to Backify");
+      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 {
+        await browserLogin();
+        console.log("Logged in to Backify");
+      }
+      ;
       break;
     case "logout":
       rmSync(configPath, { force: true });

package/package.json

@@ -1,29 +1,29 @@
-{
-  "name": "@backifydev/cli",
-  "version": "0.2.0",
-  "description": "Command-line setup and diagnostics for Backify applications",
-  "type": "module",
-  "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",
-    "prepack": "npm run build",
-    "pretypecheck": "npm run build --workspace @backify/platform",
-    "typecheck": "tsc --noEmit",
-    "pretest": "npm run build --workspace @backify/platform",
-    "test": "vitest run"
-  },
-  "publishConfig": { "access": "public" },
+{
+  "name": "@backifydev/cli",
+  "version": "0.2.2",
+  "description": "Command-line setup and diagnostics for Backify applications",
+  "type": "module",
+  "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",
+    "prepack": "npm run build",
+    "pretypecheck": "npm run build --workspace @backify/platform",
+    "typecheck": "tsc --noEmit",
+    "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://docs.backify.dev/setup",
-  "license": "MIT",
-  "engines": { "node": ">=20" },
-  "devDependencies": {
-    "@backify/platform": "*",
-    "@types/node": "^24.3.1",
-    "esbuild": "^0.25.10",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
-  }
-}
+  "homepage": "https://agent.backify.dev/",
+  "license": "MIT",
+  "engines": { "node": ">=20" },
+  "devDependencies": {
+    "@backify/platform": "*",
+    "@types/node": "^24.3.1",
+    "esbuild": "^0.25.10",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.11"
+  }
+}