fix(cli): resolve @objectstack/organizations from the host app (cloud#1013)

`objectstack serve` loaded the enterprise multi-org runtime with a bare
`import('@objectstack/organizations')`. Node ESM resolves a bare specifier
against the importer's own realpath — the CLI's, inside the framework
workspace it is linked out of — while that package is cloud-private and
lives in the served app's node_modules. The import could therefore never
succeed: every self-hosted deployment requesting a walled tenancy posture
(`group` / `isolated`) hit the ADR-0093 D5 fail-fast and exited 1, and the
only way past it was OS_ALLOW_DEGRADED_TENANCY=1 — the unwalled state D5
exists to prevent.

The file already had the right resolver (`importFromHost`), but it was
declared AFTER the auth block that contains this load, so the organizations
site could not use it. Extracted to `src/utils/import-from-host.ts`
(`createHostRequire` / `createHostImporter`), hoisted above the auth block,
and used at the organizations site.

Two adjacent corrections:

- the fallback now applies only when the host cannot RESOLVE the package. A
  host-resolved package that throws while it evaluates propagates its real
  error instead of being re-imported bare and reported as MODULE_NOT_FOUND,
  which every caller classifies as "not installed".
- the D5 fatal names the app as where the package must be installed.

Regression: `test/serve-organizations-host-resolution.e2e.test.ts` spawns the
REAL `os serve` against a temp app that carries the package in its own
node_modules. Every existing multi-org test bypasses this path (cloud's
dogfood suites pass `extraPlugins: [new OrganizationsPlugin()]`; the verify
harness posture test mocks the module), which is why the defect survived. The
new e2e fails against the bare import with the exact issue message and passes
with the fix; a second case pins that the D5 fail-fast still fires when the
app genuinely lacks the package.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019TYoxKa8yFLiDDh7tkBqtu

Author: claude

.changeset/serve-organizations-host-resolution.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `objectstack serve` resolves the enterprise multi-org runtime from the app, not from the framework (cloud#1013)
+
+Any self-hosted deployment that requested a walled tenancy posture
+(`OS_TENANCY_POSTURE=group` or `isolated`, or `OS_MULTI_ORG_ENABLED=1`) refused
+to boot:
+
+```
+✖ FATAL: tenancy posture 'isolated' was requested but @objectstack/organizations
+  could not be loaded, so the organization wall is INACTIVE. Refusing to boot.
+  cause: Cannot find package '@objectstack/organizations' imported from …/packages/cli/src/commands/serve.ts
+```
+
+…however the package was installed. `serve` loaded it with a **bare**
+`import('@objectstack/organizations')`, and Node ESM resolves a bare specifier
+against the **importer's own realpath** — the CLI's, inside the framework
+workspace it is linked out of. `@objectstack/organizations` ships in the cloud
+distribution and lives in the *served app's* `node_modules`, so that import
+could never succeed and declaring the dependency in the app changed nothing. The
+only way past the ADR-0093 D5 fail-fast was `OS_ALLOW_DEGRADED_TENANCY=1`, i.e.
+booting with the organization wall inactive — exactly the state D5 exists to
+prevent.
+
+The load now goes through the same host-app resolver `serve` already used for
+the AI service packages (`createHostImporter`, extracted to
+`src/utils/import-from-host.ts`): resolve from the host app's root, import the
+resolved path, and fall back to the CLI's own resolution only for the
+framework-owned packages the CLI itself depends on. **Declare
+`@objectstack/organizations` in your app's `package.json`** and a walled posture
+boots.
+
+Two smaller changes ride along:
+
+- A package the host resolves but that **throws while it loads** now propagates
+  its real error instead of being re-imported bare and reported as
+  `MODULE_NOT_FOUND` — a broken package used to be misreported as a missing one
+  (silently skipped for optional services, or a fatal telling the operator to
+  install what was already installed).
+- The D5 fatal now names *the app* as the place the package has to go.

packages/cli/src/commands/serve.ts

@@ -18,6 +18,7 @@ import { LOG_LEVELS, resolveLogLevel, readLogLevelEnv } from '../utils/log-level
 import { BootLogCapture, isVerboseBootLevel } from '../utils/boot-log-capture.js';
 import { graftAuthoredRuntimeMembers, isAppPluginLike } from '../utils/graft-runtime-hooks.js';
 import { redactConnectionUrl, describeDriverConnection } from '../utils/connection-display.js';
+import { createHostRequire, createHostImporter } from '../utils/import-from-host.js';
 import {
   printHeader,
   printKV,
@@ -1528,6 +1529,28 @@ export default class Serve extends Command {
         }
       }
 
+      // Host-app package resolution — shared by every optional / enterprise
+      // package loaded from here down.
+      //
+      // Node ESM resolves a bare `import(pkg)` against the IMPORTER's own
+      // realpath. The CLI is reached through a workspace/`link:` dependency, so
+      // that realpath is inside the FRAMEWORK workspace: a bare import can only
+      // see what the framework itself installed. A package supplied by the app
+      // being served — a cloud-private one such as `@objectstack/organizations`,
+      // or anything a customer installs into their own project — is invisible
+      // to it no matter what the host app declares. Resolve from the host root
+      // instead; the CLI's own resolution stays as the fallback for the
+      // framework-owned packages the CLI depends on.
+      //
+      // Defined HERE, above the auth block, because the enterprise organizations
+      // load inside it needs it: this helper used to be declared *after* that
+      // block, so the organizations load fell back to a bare import, resolved in
+      // the framework workspace, never found the cloud-private package, and every
+      // walled-posture deployment hit the ADR-0093 D5 fail-fast and exited 1
+      // (cloud#1013).
+      const hostRequire = createHostRequire();
+      const importFromHost = createHostImporter(hostRequire);
+
       // 5d. Auto-register AuthPlugin (and paired Security/Audit) when the
       // 'auth' tier is enabled and no auth plugin is already configured.
       // The Console expects /api/v1/auth/* to be served by better-auth via
@@ -1725,7 +1748,16 @@ export default class Serve extends Command {
             if (multiTenant) {
               try {
                 const organizationsPkg = '@objectstack/organizations';
-                const mod: any = await import(/* webpackIgnore: true */ organizationsPkg);
+                // Resolve from the HOST APP (cloud#1013). This package is
+                // cloud-private: it is installed in the served app's
+                // node_modules, never in the framework workspace the CLI's own
+                // realpath points at, so a bare import here could never find it
+                // — `objectstack serve` failed the fail-fast below on EVERY
+                // self-hosted walled-posture deployment, and the only way past
+                // it was OS_ALLOW_DEGRADED_TENANCY=1, i.e. exactly the unwalled
+                // state D5 exists to prevent. The host app declares the package;
+                // this resolves it from there.
+                const mod: any = await importFromHost(organizationsPkg);
                 await kernel.use(new mod.OrganizationsPlugin());
                 trackPlugin('Organizations');
               } catch (orgErr) {
@@ -1750,7 +1782,9 @@ export default class Serve extends Command {
                         '    so the organization wall is INACTIVE. Refusing to boot — a deployment that requested\n' +
                         '    multi-organization isolation must not serve traffic without it (ADR-0093 D5).\n\n' +
                         '    Fix one of:\n' +
-                        '      • install @objectstack/organizations (the enterprise multi-org runtime), or\n' +
+                        '      • add @objectstack/organizations (the enterprise multi-org runtime) to THIS APP\n' +
+                        "        — declare it in the app's package.json and install; the CLI resolves it from the\n" +
+                        '          app, not from the framework it is linked out of — or\n' +
                         "      • set OS_TENANCY_POSTURE=single (or unset OS_MULTI_ORG_ENABLED) to run single-org, or\n" +
                         '      • set OS_ALLOW_DEGRADED_TENANCY=1 to boot in an explicitly degraded single-org state.\n\n' +
                         `    cause: ${cause}\n`,
@@ -1918,23 +1952,11 @@ export default class Serve extends Command {
         (p: any) => p.name === 'com.objectstack.service-ai'
             || p.constructor?.name === 'AIServicePlugin'
       );
-      // Resolve optional plugin packages from the HOST APP's context (the app
-      // being served declares them as deps — including private packages like
+      // `importFromHost` (declared above, before the auth block) resolves
+      // optional plugin packages from the HOST APP's context — the app being
+      // served declares them as deps, including private packages like
       // @objectstack/service-ai-studio that the framework CLI itself does not
-      // depend on). A bare import would resolve relative to the CLI's location
-      // and miss a package linked into the app's node_modules. Falls back to a
-      // bare import for framework-owned packages.
-      const { createRequire: _createRequire } = await import('node:module');
-      const { pathToFileURL: _pathToFileURL } = await import('node:url');
-      const _nodePath = await import('node:path');
-      const _hostRequire = _createRequire(_nodePath.join(process.cwd(), 'package.json'));
-      const importFromHost = async (pkg: string): Promise<any> => {
-        try {
-          return await import(_pathToFileURL(_hostRequire.resolve(pkg)).href);
-        } catch {
-          return import(/* webpackIgnore: true */ pkg);
-        }
-      };
+      // depend on.
       // [CE AI opt-in] Auto-register the headless AI service ONLY when the host
       // app DECLARES the AI service (or the cloud AI Studio that builds on it).
       // Declaration is the edition boundary: a Community-Edition app that omits
@@ -1947,7 +1969,7 @@ export default class Serve extends Command {
       const hostDeclaresDependency = (pkg: string): boolean => {
         try {
           const hostPkg = JSON.parse(
-            _fs.readFileSync(_hostRequire.resolve('./package.json'), 'utf8'),
+            _fs.readFileSync(hostRequire.resolve('./package.json'), 'utf8'),
           ) as Record<string, Record<string, string> | undefined>;
           return Boolean(
             hostPkg.dependencies?.[pkg] ?? hostPkg.devDependencies?.[pkg]

packages/cli/src/utils/import-from-host.test.ts

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * cloud#1013 — resolving a host-app package from the CLI.
+ *
+ * The defect: `serve` loaded `@objectstack/organizations` with a BARE
+ * `import()`. Node ESM resolves that against the importer's own realpath — the
+ * CLI's, inside the framework workspace — while the package is cloud-private
+ * and only ever exists in the served app's `node_modules`. It could therefore
+ * never resolve, and every walled tenancy posture died on the ADR-0093 D5
+ * fail-fast.
+ *
+ * These cases run against a REAL fixture app on disk (a real `node_modules`,
+ * real resolution, nothing mocked): the first two are the issue's own repro,
+ * one half per case — the CLI's resolution cannot see the package, the host
+ * app's can.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHostImporter, createHostRequire } from './import-from-host.js';
+
+/** The cloud-private package at the heart of cloud#1013. */
+const ORGANIZATIONS = '@objectstack/organizations';
+/** A package that fails while it EVALUATES — not while it resolves. */
+const BROKEN = '@fixture/throws-on-load';
+
+/** `packages/cli` — what a bare `import()` inside the CLI resolves against. */
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+let hostRoot: string;
+
+function writeFixturePackage(root: string, name: string, indexJs: string): void {
+  const dir = join(root, 'node_modules', ...name.split('/'));
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, 'package.json'),
+    JSON.stringify({ name, version: '0.0.0-fixture', type: 'module', main: 'index.js' }),
+    'utf8',
+  );
+  writeFileSync(join(dir, 'index.js'), indexJs, 'utf8');
+}
+
+beforeAll(() => {
+  // A host app exactly as the fix expects one: it DECLARES the enterprise
+  // package and has it installed in its own node_modules. The framework
+  // workspace the CLI lives in has neither.
+  hostRoot = mkdtempSync(join(tmpdir(), 'os-import-from-host-'));
+  writeFileSync(
+    join(hostRoot, 'package.json'),
+    JSON.stringify({
+      name: 'host-app-fixture',
+      type: 'module',
+      dependencies: { [ORGANIZATIONS]: '*' },
+    }),
+    'utf8',
+  );
+  writeFixturePackage(
+    hostRoot,
+    ORGANIZATIONS,
+    'export class OrganizationsPlugin { name = "com.objectstack.organizations"; }\n',
+  );
+  writeFixturePackage(hostRoot, BROKEN, 'throw new Error("fixture package exploded on import");\n');
+});
+
+afterAll(() => {
+  if (hostRoot) rmSync(hostRoot, { recursive: true, force: true });
+});
+
+describe('host-app package resolution (cloud#1013)', () => {
+  it('the CLI\'s own resolution cannot see a host-only package — the defect', () => {
+    // Literally the issue's repro, from `packages/cli`:
+    //   node -e "require.resolve('@objectstack/organizations')" -> MODULE_NOT_FOUND
+    // A bare `import()` in serve.ts resolved from exactly here, which is why
+    // declaring the dependency in the app changed nothing.
+    expect(() => createHostRequire(CLI_ROOT).resolve(ORGANIZATIONS)).toThrow(
+      /Cannot find module/,
+    );
+  });
+
+  it('resolves a package that exists ONLY in the host app', async () => {
+    const importFromHost = createHostImporter(createHostRequire(hostRoot));
+    const mod = await importFromHost(ORGANIZATIONS);
+    // The export `serve` constructs: `new mod.OrganizationsPlugin()`.
+    expect(typeof mod.OrganizationsPlugin).toBe('function');
+    expect(new mod.OrganizationsPlugin().name).toBe('com.objectstack.organizations');
+  });
+
+  it('falls back to the CLI\'s own resolution when the host cannot resolve', async () => {
+    // Whatever the host app cannot see must still load from the CLI's own
+    // dependencies — that fallback is what keeps every framework-owned load in
+    // `serve` (plugin-auth, plugin-security, service-i18n, …) working exactly
+    // as before. Modelled with a host `require` that resolves nothing, because
+    // a real one cannot: vitest exports NODE_PATH into the test process, so
+    // every package in the workspace store resolves from any directory.
+    const blindHostRequire = {
+      resolve(pkg: string): string {
+        throw Object.assign(new Error(`Cannot find module '${pkg}'`), { code: 'MODULE_NOT_FOUND' });
+      },
+    } as unknown as NodeRequire;
+    const mod = await createHostImporter(blindHostRequire)('chalk');
+    expect(typeof mod.default.green).toBe('function');
+  });
+
+  it('reports a package that neither can resolve as module-not-found', async () => {
+    const importFromHost = createHostImporter(createHostRequire(hostRoot));
+    // Callers classify "missing vs crashed" off this error (Serve.
+    // isModuleNotFoundError), so the absent case must stay recognisable.
+    await expect(importFromHost('@fixture/nowhere-at-all')).rejects.toThrow(
+      /Cannot find (module|package)|Failed to (load|resolve)/,
+    );
+  });
+
+  it('propagates an evaluation crash instead of masking it as module-not-found', async () => {
+    // A host-resolved package that THROWS while loading is a broken package,
+    // not a missing one. Re-importing it bare (the shape this helper replaced)
+    // would swap the real cause for a MODULE_NOT_FOUND, which every caller
+    // reads as "not installed" — a crash silently downgraded to a skip, or a
+    // fatal telling the operator to install what is already installed.
+    const importFromHost = createHostImporter(createHostRequire(hostRoot));
+    await expect(importFromHost(BROKEN)).rejects.toThrow(/fixture package exploded on import/);
+  });
+});

packages/cli/src/utils/import-from-host.ts

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Resolve optional packages from the **host app**, not from the CLI.
+ *
+ * Node ESM resolves a bare `import('pkg')` against the **importer's own
+ * realpath**. The CLI is reached through a `link:`/workspace dependency, so its
+ * realpath is inside the *framework* workspace — a bare import from
+ * `packages/cli` can only ever see packages installed in the framework's own
+ * `node_modules`. Every package that lives OUTSIDE that workspace and is
+ * supplied by the app being served — a cloud-private package such as
+ * `@objectstack/organizations` or `@objectstack/service-ai-studio`, or anything
+ * a customer installs into their own project — is therefore invisible to a bare
+ * import, no matter what the host app declares in its `package.json`
+ * (cloud#1013: `objectstack serve` could never load the enterprise multi-org
+ * runtime, so every self-hosted walled-posture deployment hit the ADR-0093 D5
+ * fail-fast and exited 1).
+ *
+ * The fix is to resolve from the host app's root and import the resolved
+ * absolute path. The CLI's own resolution stays as the fallback, for the
+ * framework-owned packages the CLI itself depends on and the host does not
+ * declare.
+ *
+ * Resolution failure is the ONLY thing that falls back. A package the host
+ * resolves but that throws while it evaluates is a genuine crash and propagates
+ * unchanged: re-importing it bare would replace the real cause with a
+ * `MODULE_NOT_FOUND`, which every caller here classifies as "not installed" —
+ * turning a broken package into a silent skip (or, on the organizations path,
+ * into a fatal message telling the operator to install what is already there).
+ */
+
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Imports a package as the host app would see it.
+ *
+ * `any` is the module namespace of a package this repo does not compile against
+ * (it is not a dependency of the CLI at all) — every call site reads an export
+ * off it dynamically, exactly as the bare `import()` it replaces did.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HostImporter = (pkg: string) => Promise<any>;
+
+/**
+ * A `require` anchored at the **host app's** `package.json` — i.e. the project
+ * `objectstack serve` was invoked in, whose `node_modules` carries the packages
+ * it declares.
+ *
+ * @param hostRoot Directory holding the host app's `package.json` (default: the
+ * process CWD, which is where the CLI reads `objectstack.config.ts` from too).
+ */
+export function createHostRequire(hostRoot: string = process.cwd()): NodeRequire {
+  return createRequire(join(hostRoot, 'package.json'));
+}
+
+/**
+ * Build an importer that resolves from the host app first, then falls back to
+ * the CLI's own resolution.
+ *
+ * @param hostRequire Reuse an existing host `require` (callers usually also need
+ * it to read the host `package.json`); defaults to one anchored at the CWD.
+ */
+export function createHostImporter(
+  hostRequire: NodeRequire = createHostRequire(),
+): HostImporter {
+  return async (pkg: string): Promise<any> => {
+    let resolved: string;
+    try {
+      resolved = hostRequire.resolve(pkg);
+    } catch {
+      // Invisible to the host app — try the CLI's own dependencies. A package
+      // neither can see throws MODULE_NOT_FOUND from here, which is what the
+      // callers' "missing vs crashed" classification expects.
+      return import(/* webpackIgnore: true */ pkg);
+    }
+    return import(pathToFileURL(resolved).href);
+  };
+}