@backifydev/cli 0.2.1 → 0.2.2

package/README.md

@@ -13,6 +13,8 @@ npx @backifydev/cli login
 
 `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/).

package/dist/index.js

@@ -14,7 +14,7 @@ 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 });
@@ -41,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 } };
@@ -92,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");
 }
@@ -118,7 +168,7 @@ 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://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" });
 }
@@ -139,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 {
@@ -239,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;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backifydev/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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": {