@avocadostudio-ai/site-sdk 0.11.8 → 0.12.0

package/dist/cli/register-notice.d.ts

@@ -1,5 +1,19 @@
 /** Where the standalone orchestrator listens, and what the editor assumes. */
 export declare const DEFAULT_ORCHESTRATOR = "http://localhost:4200";
+/**
+ * What to print when the POST could not connect at all.
+ *
+ * This used to say `pnpm dev:orchestrator`, which is a script in Avocado's own
+ * monorepo and does not exist in the project the reader is standing in. Most
+ * readers reaching this message are in library mode, where there is no
+ * orchestrator to start: it is mounted inside their own Next app, so the only
+ * thing that can be down is `next dev`, and the only thing that can be wrong is
+ * this command's target — which defaults to the standalone address.
+ *
+ * `port` is the site's dev port, so the suggestion is the URL they would
+ * actually pass rather than a shape to fill in.
+ */
+export declare function unreachableOrchestratorNotice(orchestrator: string, port: number): string;
 /**
  * The warning that makes "the site should appear in the dashboard" honest, or
  * `null` when it already is.

package/dist/cli/register-notice.js

@@ -5,6 +5,34 @@
  */
 /** Where the standalone orchestrator listens, and what the editor assumes. */
 export const DEFAULT_ORCHESTRATOR = "http://localhost:4200";
+/**
+ * What to print when the POST could not connect at all.
+ *
+ * This used to say `pnpm dev:orchestrator`, which is a script in Avocado's own
+ * monorepo and does not exist in the project the reader is standing in. Most
+ * readers reaching this message are in library mode, where there is no
+ * orchestrator to start: it is mounted inside their own Next app, so the only
+ * thing that can be down is `next dev`, and the only thing that can be wrong is
+ * this command's target — which defaults to the standalone address.
+ *
+ * `port` is the site's dev port, so the suggestion is the URL they would
+ * actually pass rather than a shape to fill in.
+ */
+export function unreachableOrchestratorNotice(orchestrator, port) {
+    const libraryUrl = `http://localhost:${port}/api/avocado`;
+    const targetedDefault = orchestrator.replace(/\/+$/, "") === DEFAULT_ORCHESTRATOR;
+    return (`\nCould not reach an orchestrator at ${orchestrator}.\n` +
+        (targetedDefault
+            ? `\nThat is the STANDALONE server's address, which is this command's default\n` +
+                `and is wrong for most integrations. If you mounted createOrchestrator\n` +
+                `inside your own app (library mode), the orchestrator is part of your dev\n` +
+                `server and the target is:\n\n` +
+                `  npx avocado-register --name "…" --orchestrator ${libraryUrl}\n\n` +
+                `If you are running the standalone server, start it and re-run this.\n`
+            : `\nCheck that the URL is right and that whatever serves it is up. In library\n` +
+                `mode that is your own dev server — the orchestrator is mounted inside it,\n` +
+                `so there is no separate process to start.\n`));
+}
 /**
  * The warning that makes "the site should appear in the dashboard" honest, or
  * `null` when it already is.

package/dist/cli/register.d.ts

@@ -14,7 +14,9 @@
  *      DRAFT_MODE_SECRET. If missing, generates a cryptographically random
  *      secret (32 random bytes, hex-encoded) and writes it to `.env.local`.
  *      Also fills in ORCHESTRATOR_URL and the NEXT_PUBLIC_* vars if absent.
- *   3. POSTs the site config to `<ORCHESTRATOR_URL>/sites/register`.
+ *   3. POSTs the site config to `<ORCHESTRATOR_URL>/sites/register`. Optional
+ *      in library mode, where the mount already knows its one site — so an
+ *      orchestrator it cannot reach is reported, not treated as failure.
  *   4. Prints next steps (and any warnings the orchestrator returned about
  *      secret mismatches with the editor's build-time config).
  *
@@ -26,7 +28,8 @@
  * Defaults:
  *   --id            kebab-case of --name (or the project's package.json `name`)
  *   --port          parsed from `scripts.dev` in package.json, falls back to 3000
- *   --orchestrator  $ORCHESTRATOR_URL or http://localhost:4200
+ *   --orchestrator  $ORCHESTRATOR_URL, .env.local's ORCHESTRATOR_URL, or
+ *                   http://localhost:4200 (the standalone server)
  *   --session       dev
  *   --cwd           process.cwd()
  */

package/dist/cli/register.js

@@ -14,7 +14,9 @@
  *      DRAFT_MODE_SECRET. If missing, generates a cryptographically random
  *      secret (32 random bytes, hex-encoded) and writes it to `.env.local`.
  *      Also fills in ORCHESTRATOR_URL and the NEXT_PUBLIC_* vars if absent.
- *   3. POSTs the site config to `<ORCHESTRATOR_URL>/sites/register`.
+ *   3. POSTs the site config to `<ORCHESTRATOR_URL>/sites/register`. Optional
+ *      in library mode, where the mount already knows its one site — so an
+ *      orchestrator it cannot reach is reported, not treated as failure.
  *   4. Prints next steps (and any warnings the orchestrator returned about
  *      secret mismatches with the editor's build-time config).
  *
@@ -26,14 +28,15 @@
  * Defaults:
  *   --id            kebab-case of --name (or the project's package.json `name`)
  *   --port          parsed from `scripts.dev` in package.json, falls back to 3000
- *   --orchestrator  $ORCHESTRATOR_URL or http://localhost:4200
+ *   --orchestrator  $ORCHESTRATOR_URL, .env.local's ORCHESTRATOR_URL, or
+ *                   http://localhost:4200 (the standalone server)
  *   --session       dev
  *   --cwd           process.cwd()
  */
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { DEFAULT_ORCHESTRATOR, orchestratorMismatchNotice } from "./register-notice.js";
+import { DEFAULT_ORCHESTRATOR, orchestratorMismatchNotice, unreachableOrchestratorNotice, } from "./register-notice.js";
 function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -98,7 +101,12 @@ REQUIRED
 OPTIONAL
   --id <kebab-case>         Site ID (default: kebab-case of name or package.json name)
   --port <number>           Dev server port (default: parsed from package.json scripts.dev, or 3000)
-  --orchestrator <url>      Orchestrator URL (default: $ORCHESTRATOR_URL or http://localhost:4200)
+  --orchestrator <url>      Orchestrator URL. Default: $ORCHESTRATOR_URL, else
+                            ORCHESTRATOR_URL from .env.local, else
+                            http://localhost:4200 — which is the STANDALONE
+                            server. In library mode the orchestrator is mounted
+                            inside your own app, so the target is your dev
+                            server: http://localhost:<port>/api/avocado
   --secret <string>         DRAFT_MODE_SECRET (default: read from .env.local, or generate random)
   --session <string>        Orchestrator session (default: dev)
   --purpose <string>        One-line site description for AI context
@@ -202,6 +210,20 @@ function mergeEnvFile(envPath, existing, additions) {
     writeFileSync(envPath, original + newLines.join("\n") + "\n", "utf-8");
     return added;
 }
+/**
+ * What was written to `.env.local`, in a form that reads the same whether or
+ * not the registration that follows it succeeded — because this half runs
+ * first and is the half the site cannot work without.
+ */
+function envReport(envPath, added, secretGenerated, secret) {
+    const secretLine = secretGenerated
+        ? `  Secret:       generated (${secret.slice(0, 8)}…)\n`
+        : `  Secret:       reused from .env.local\n`;
+    const fileLine = added.length > 0
+        ? `\n${envPath} updated. Added: ${added.join(", ")}\n`
+        : `\n${envPath} unchanged (all keys already present).\n`;
+    return secretLine + fileLine;
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
@@ -224,8 +246,23 @@ async function main() {
     }
     // Resolve port
     const port = args.port ?? detectPortFromPackageJson(pkg) ?? 3000;
-    // Resolve orchestrator URL
-    const orchestrator = (args.orchestrator ?? process.env.ORCHESTRATOR_URL ?? DEFAULT_ORCHESTRATOR).replace(/\/+$/, "");
+    const envPath = join(cwd, ".env.local");
+    const existingEnv = existsSync(envPath) ? parseEnvFile(readFileSync(envPath, "utf-8")) : {};
+    /*
+     * `.env.local` outranks the built-in default.
+     *
+     * A library-mode project has `ORCHESTRATOR_URL=http://localhost:3000/api/avocado`
+     * sitting in that file — the quickstart writes it, and so does this command.
+     * Reading the file only *after* resolving the target meant a second run
+     * ignored what the first one wrote, defaulted to the standalone address,
+     * registered with whatever happened to be listening on :4200, and reported
+     * success. The file is the project saying where its orchestrator is; only an
+     * explicit flag or the caller's own environment should outrank it.
+     */
+    const orchestratorAsserted = args.orchestrator ?? process.env.ORCHESTRATOR_URL;
+    const orchestrator = (orchestratorAsserted ??
+        existingEnv.ORCHESTRATOR_URL ??
+        DEFAULT_ORCHESTRATOR).replace(/\/+$/, "");
     /*
      * A credentialed orchestrator refuses `/sites/register` like any other route,
      * and this CLI had no way to present a token — so the documented path for
@@ -234,18 +271,25 @@ async function main() {
      */
     const accessToken = (args.token ?? process.env.ORCHESTRATOR_ACCESS_TOKEN ?? "").trim();
     // Resolve / generate the draft secret
-    const envPath = join(cwd, ".env.local");
-    const existingEnv = existsSync(envPath) ? parseEnvFile(readFileSync(envPath, "utf-8")) : {};
     let secret = args.secret ?? existingEnv.DRAFT_MODE_SECRET;
     let secretGenerated = false;
     if (!secret) {
         secret = randomBytes(32).toString("hex");
         secretGenerated = true;
     }
-    // Append-only merge — only add keys that aren't already present, preserving
-    // the user's existing file formatting and comments.
+    /*
+     * Append-only merge — only add keys that aren't already present, preserving
+     * the user's existing file formatting and comments.
+     *
+     * `ORCHESTRATOR_URL` is held back unless the caller named it, and written
+     * after the registration answers. A default nobody chose, recorded in the
+     * project's env file, is a guess promoted to configuration: the run that
+     * could not reach :4200 would write :4200 anyway, and every later run would
+     * then read it back as the project's own answer. Everything else here is
+     * independent of whether any orchestrator exists.
+     */
     const added = mergeEnvFile(envPath, existingEnv, {
-        ORCHESTRATOR_URL: orchestrator,
+        ...(orchestratorAsserted ? { ORCHESTRATOR_URL: orchestrator } : {}),
         DRAFT_MODE_SECRET: secret,
         NEXT_PUBLIC_DEFAULT_SITE_ID: siteId,
         NEXT_PUBLIC_SITE_NAME: name,
@@ -278,11 +322,28 @@ async function main() {
         });
     }
     catch (err) {
+        /*
+         * Unreachable is not failure. The env half of this command already ran —
+         * the secret is generated and the four variables are in `.env.local` — and
+         * that is the half a site cannot work without. Registration is the optional
+         * half: a library-mode mount already knows the one site it serves and
+         * reports it from `GET /sites` whether or not anyone registered it.
+         *
+         * Exiting 1 here described the run as a total failure, so integrators
+         * re-ran it, hand-edited `.env.local` against the advice not to, or went
+         * looking for a service they never needed. Say precisely which half
+         * happened and leave the exit code clean. An orchestrator that ANSWERS and
+         * refuses is a different matter and still exits 1 below.
+         */
         const aborted = err.name === "AbortError";
-        process.stderr.write(`\nError: could not reach the orchestrator at ${orchestrator}\n`);
-        process.stderr.write(`  ${aborted ? "Request timed out after 10 seconds." : err.message}\n`);
-        process.stderr.write(`\nMake sure the orchestrator is running:\n  pnpm dev:orchestrator\n`);
-        process.exit(1);
+        process.stdout.write(envReport(envPath, added, secretGenerated, secret));
+        process.stdout.write(unreachableOrchestratorNotice(orchestrator, port));
+        process.stdout.write(`  (${aborted ? "timed out after 10 seconds" : err.message})\n`);
+        process.stdout.write(`\nThe site is NOT registered. Nothing else is missing: in library mode the\n` +
+            `orchestrator already serves the one site it is mounted in, so open the\n` +
+            `editor and it should be there. Re-run this command to add the name,\n` +
+            `preview URL and purpose to its registry.\n\n`);
+        process.exit(0);
     }
     finally {
         clearTimeout(timeoutId);
@@ -298,23 +359,20 @@ async function main() {
         process.exit(1);
     }
     const result = (await response.json());
+    /*
+     * Now it is not a guess: something answered `/sites/register` there, so the
+     * URL is worth recording for the next run and for the SDK's server-side draft
+     * fetch, which falls back to :4200 when nothing is set.
+     */
+    if (!orchestratorAsserted) {
+        added.push(...mergeEnvFile(envPath, existingEnv, { ORCHESTRATOR_URL: orchestrator }));
+    }
     // Friendly output
     process.stdout.write(`\nRegistered "${name}" with the orchestrator.\n`);
     process.stdout.write(`  Site ID:      ${siteId}\n`);
     process.stdout.write(`  Preview URL:  ${previewUrl}\n`);
     process.stdout.write(`  Orchestrator: ${orchestrator}\n`);
-    if (secretGenerated) {
-        process.stdout.write(`  Secret:       generated (${secret.slice(0, 8)}…)\n`);
-    }
-    else {
-        process.stdout.write(`  Secret:       reused from .env.local\n`);
-    }
-    if (added.length > 0) {
-        process.stdout.write(`\n.env.local updated. Added: ${added.join(", ")}\n`);
-    }
-    else {
-        process.stdout.write(`\n.env.local unchanged (all keys already present).\n`);
-    }
+    process.stdout.write(envReport(envPath, added, secretGenerated, secret));
     if (Array.isArray(result.warnings) && result.warnings.length > 0) {
         process.stdout.write(`\nWarnings:\n`);
         for (const w of result.warnings) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -147,17 +147,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.11.8",
-    "@avocadostudio-ai/preview-adapter": "^0.11.8",
-    "@avocadostudio-ai/richtext": "^0.11.8",
-    "@avocadostudio-ai/shared": "^0.11.8"
+    "@avocadostudio-ai/blocks": "^0.12.0",
+    "@avocadostudio-ai/preview-adapter": "^0.12.0",
+    "@avocadostudio-ai/shared": "^0.12.0",
+    "@avocadostudio-ai/richtext": "^0.12.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.11.8"
+    "@avocadostudio-ai/orchestrator-core": "^0.12.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {