@backifydev/cli 0.2.0

package/README.md

@@ -0,0 +1,13 @@
+# @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
+```
+
+`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).

package/dist/index.js

@@ -0,0 +1,210 @@
+#!/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";
+
+// src/setup.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// ../platform/dist/index.js
+var INSTRUCTION_VERSION = 1;
+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 });
+var CAPABILITIES = [
+  capability("auth", "auth", "Application users, organizations, roles, and permissions"),
+  capability("database", "db", "Persistent application data", true),
+  capability("storage", "storage", "Persistent files and objects", true),
+  capability("functions", "functions", "Server function declarations"),
+  capability("jobs", "jobs", "Reliable background work", true),
+  capability("scheduler", "jobs.schedule", "Scheduled job declarations"),
+  capability("events", "events", "Application events and subscriptions"),
+  capability("secrets", "secrets", "Server-side secret retrieval", true),
+  capability("http", "http", "Governed outbound HTTP"),
+  capability("ai", "ai", "Provider-independent generative AI"),
+  capability("audit", "audit", "Structured audit records"),
+  capability("logs", "logs", "Structured application logging"),
+  capability("config", "config", "Non-secret application configuration")
+];
+var CAPABILITY_REGISTRY = Object.fromEntries(CAPABILITIES.map((x) => [x.name, x]));
+var MANAGED_START = "<!-- BACKIFY:MANAGED:START -->";
+var MANAGED_END = "<!-- BACKIFY:MANAGED:END -->";
+function managedInstructions() {
+  return `${MANAGED_START}
+
+# Backify Platform Instructions
+
+This application runs on Backify.
+
+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.
+
+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.
+
+The authoritative documentation is ${DOCS_URL}. If unsure, check it before adding an external platform dependency. Preserve all repository instructions outside this managed block.
+
+${MANAGED_END}`;
+}
+function updateManagedInstructions(content) {
+  const block = managedInstructions(), start = content.indexOf(MANAGED_START), end = content.indexOf(MANAGED_END);
+  if (start >= 0 && end >= start)
+    return content.slice(0, start) + block + content.slice(end + MANAGED_END.length);
+  return content.trim() ? `${content.trimEnd()}
+
+${block}
+` : `${block}
+`;
+}
+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 } };
+}
+function validateConfig(value) {
+  const errors = [];
+  if (!value || typeof value !== "object")
+    return ["backify.json must contain an object"];
+  const x = value;
+  if (x.platform !== "backify")
+    errors.push("platform must be 'backify'");
+  if (x.sdk !== SDK_PACKAGE)
+    errors.push(`sdk must be '${SDK_PACKAGE}'`);
+  if (typeof x.appId !== "string" || !/^app_[A-Za-z0-9_-]+$/.test(x.appId))
+    errors.push("appId must use the app_<id> format");
+  if (!Number.isInteger(x.instructionVersion) || Number(x.instructionVersion) < 1)
+    errors.push("instructionVersion must be a positive integer");
+  if (x.instructions?.preferBackifyCapabilities !== true)
+    errors.push("instructions.preferBackifyCapabilities must be true");
+  if (x.instructions?.allowDirectCloudInfrastructure !== false)
+    errors.push("instructions.allowDirectCloudInfrastructure must be false");
+  return errors;
+}
+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/setup.ts
+var instructionFiles = ["AGENTS.md", "CLAUDE.md", join(".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;
+  return "npm";
+}
+function updateInstructions(root = process.cwd()) {
+  for (const relative of instructionFiles) {
+    const path = join(root, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, updateManagedInstructions(existsSync(path) ? readFileSync(path, "utf8") : ""));
+  }
+}
+function writeConfig(appId, root = process.cwd()) {
+  writeFileSync(join(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"));
+    return Boolean(pkg.dependencies?.[SDK_PACKAGE] || pkg.devDependencies?.[SDK_PACKAGE]);
+  } catch {
+    return false;
+  }
+}
+function installSdk(root = process.cwd()) {
+  if (sdkInstalled(root)) return;
+  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 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");
+  if (install) installSdk(root);
+  writeConfig(appId, root);
+  updateInstructions(root);
+}
+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"));
+    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.`);
+  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`);
+  }
+  let version = "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync(join(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/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" };
+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();
+}
+var option = (name) => {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : void 0;
+};
+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.");
+      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}.`);
+      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}`);
+      if (!result.valid) process.exitCode = 1;
+      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");
+      break;
+    case "logout":
+      rmSync(configPath, { force: true });
+      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" }) }));
+      break;
+    default:
+      console.log("backify init --app app_xxxxx | sync | doctor | login | logout | apps | deploy");
+  }
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +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" },
+  "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"
+  }
+}