@bizone-ai/cli 0.1.6 → 0.1.8

package/README.md

@@ -63,7 +63,7 @@ bizone <category> <command> [args] [--no-colors]
 | `start`         | —           | Start the platform                              |
 | `stop`          | —           | Stop the platform                               |
 | `configuration` | `config`,`c`| General CLI configuration                       |
-| `images`        | `img`       | Override container image URLs                   |
+| `images`        | `img`       | Override image URLs / add custom services       |
 | `environment`   | `env`       | Set environment variables per container         |
 | `resources`     | `res`, `r`  | Resources imported into the resource-manager    |
 | `database`      | `db`        | Manage the bundled MySQL database               |
@@ -92,7 +92,8 @@ File shape:
   "config":    { "key": "value" },
   "images":    { "type": "image-url" },
   "env":       { "type": { "NAME": "value" } },
-  "resources": { "namespace": "path" }
+  "resources": { "namespace": "path" },
+  "custom":    { "id": "path-to-service.json" }
 }
 ```
 
@@ -137,9 +138,10 @@ bizone config set cloud_tools_enable true
 ## `images` — override container images
 
 ```bash
-bizone images get                 # list image URLs (override or default)
+bizone images get                 # list image URLs + custom services
 bizone images set {type} {url}    # override an image
-bizone images remove {type}       # reset to default
+bizone images remove {type|id}    # reset an image, or unregister a custom service
+bizone images add {id} {path}     # register an additional custom service
 ```
 
 Stored at `$.images.{type}`. Valid types:
@@ -152,6 +154,61 @@ Example:
 bizone images set state-store bizone-local/state-store:1.0.0
 ```
 
+### Additional custom services (`images add`)
+
+Register extra services that aren't part of the built-in topology. Each is
+identified by an `{id}` and points to a JSON file describing the service, using
+the **same shape as the built-in service objects** (see
+`src/containers/mysql.js`):
+
+```bash
+bizone images add {id} {path-to-service.json}    # register / update
+bizone images remove {id}                        # unregister
+```
+
+Stored at `$.custom.{id}`. The JSON file shape:
+
+```json
+{
+  "type": "redis",
+  "image": "redis:7",
+  "containerName": "bizone-redis",
+  "containerPort": 6379,
+  "portKey": "redis_port",
+  "defaultPort": "6379",
+  "enableKey": null,
+  "readyPath": "/.system/status",
+  "readyCheck": "systemStatusOk",
+  "volume": { "name": "bizone-redis-data", "mount": "/data" },
+  "defaultEnv": { "SOME_VAR": "value" }
+}
+```
+
+- **`image`** and **`containerName`** are required; everything else is optional.
+- `containerName` should start with `bizone-` (so `db destroy` recognizes it)
+  and must not collide with a built-in container.
+- `type` defaults to the `{id}` if omitted; it is the key for image/env
+  overrides (`bizone env set {type} ...`).
+- `readyCheck` (optional) must be one of `systemStatusOk`, `uiReadinessUp`,
+  `mysqlPing`. With `systemStatusOk`/`uiReadinessUp` the CLI polls
+  `http://localhost:{port}{readyPath}`; with `mysqlPing` it uses `mysqladmin
+  ping`. Omit both `readyPath` and `readyCheck` to skip the readiness wait.
+- `enableKey` (optional) — a config key gating the service. Omit / `null` to
+  always run.
+
+Custom services are validated when added (the CLI parses the file immediately).
+They **start last**, after the built-in platform is ready, and are **stopped by
+`bizone stop`** like any other container. Relative `{path}` values resolve
+against the `.bizone` config directory.
+
+Example:
+
+```bash
+bizone images add redis ./redis.json
+bizone start          # built-ins first, then redis
+bizone images get     # redis shown under "Custom services"
+```
+
 ---
 
 ## `environment` — per-container environment variables
@@ -198,6 +255,7 @@ namespace.
 bizone resources get                       # list configured sources
 bizone resources set {namespace} {path}    # set a file or folder source
 bizone resources remove {namespace}        # remove a namespace source
+bizone resources import [global]           # import now (see below)
 ```
 
 Stored at `$.resources.{namespace}`. `{path}` may be:
@@ -224,6 +282,20 @@ POST http://localhost:{resource_manager_port}/admin/{namespace}/status
 { "user": "bizone-cli", "message": "resource initialization", "items": [ ... ] }
 ```
 
+### `resources import` — import on demand
+
+Run an import against the **already-running** platform (resource-manager must be up):
+
+```bash
+bizone resources import          # import the user-configured namespaces (above)
+bizone resources import global   # run ONLY the bizone-resources job (core resources)
+```
+
+- Without `global`: imports the namespaces configured via `resources set`.
+- With `global`: runs the one-shot `bizone-resources` docker job, which imports
+  the **core** resources into the `.global` namespace. This is the same job
+  `bizone start` runs (unconditionally here — used to (re)seed core resources).
+
 ---
 
 ## `start` — start the platform
@@ -246,6 +318,11 @@ returns control to the shell. Container ids are saved to
 3. Start `resource-manager`; wait until `GET /.system/status` returns `{ "status": "OK" }`.
 4. Run the `bizone-resources` initialization job (blocking).
 5. Import any configured `resources` namespaces (see above).
+
+   Steps 4–5 are **skipped entirely if the core resources were already
+   imported**, detected by querying
+   `GET /.global/resources?id=action/flow.start&expand=no`; a `200` with a
+   non-empty `items` array means the import already happened.
 6. Start `orchestrator`, `ui`, and any enabled optional services in parallel
    (state-store / cloud-tools run only when `*_enable=true`).
    - The orchestrator receives the AWS env vars when `forward_aws_env=true`.
@@ -253,6 +330,8 @@ returns control to the shell. Container ids are saved to
    - `ui` — `GET /actuator/health/readiness` returns `{"status":{"code":"UP"}}`
    - all others — `GET /.system/status` returns `{ "status": "OK" }`
    - each wait times out after `timeout_sec` seconds.
+8. Start any **custom services** registered with `bizone images add` (last),
+   then wait for the readiness each declares (see the `images add` section).
 
 Each container is started with:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bizone-ai/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Assistant CLI for running the Bizone orchestrator platform locally with Docker",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "start": "node bin/bizone.js",
-    "test": "echo No tests"
+    "test": "node --test test/*.test.js"
   },
   "license": "UNLICENSED"
 }

package/src/cli.js

@@ -66,7 +66,10 @@ function printHelp() {
   );
   log.plain(`  ${c("bizone images set {type} {url}")}   Override an image`);
   log.plain(
-    `  ${c("bizone images remove {type}")}      Reset image to default`,
+    `  ${c("bizone images remove {type|id}")}   Reset image / drop custom service`,
+  );
+  log.plain(
+    `  ${c("bizone images add {id} {path}")}    Register a custom service (json)`,
   );
   log.plain("");
   log.plain(b("Environment:") + color.dim("  (env)"));
@@ -84,6 +87,9 @@ function printHelp() {
   log.plain(
     `  ${c("bizone resources remove {namespace}")}  Remove a resource source`,
   );
+  log.plain(
+    `  ${c("bizone resources import [global]")}  Import user resources (or core with 'global')`,
+  );
   log.plain("");
   log.plain(b("Database:") + color.dim("  (db)"));
   log.plain(

package/src/commands/images.js

@@ -1,7 +1,8 @@
-// `bizone images|img get|set|remove`
+// `bizone images|img get|set|remove|add`
 
 import { loadConfig, saveConfig } from "../config.js";
 import { CONTAINERS, IMAGE_TYPES } from "../defaults.js";
+import { readCustomService } from "../custom-services.js";
 import { color, log } from "../colors.js";
 
 function isValidType(type) {
@@ -29,6 +30,38 @@ export function images(args) {
           : color.dim(" (default)");
         log.plain(`  ${color.cyan(t)} -> ${val}${tag}`);
       }
+      const custom = Object.entries(cfg.custom || {});
+      if (custom.length > 0) {
+        log.plain(color.bold("Custom services:"));
+        for (const [id, path] of custom) {
+          log.plain(`  ${color.cyan(id)} -> ${path}${color.dim(" (custom)")}`);
+        }
+      }
+      return 0;
+    }
+    case "add": {
+      if (!type || rest.length === 0) {
+        log.err("Usage: bizone images add {id} {path-to-service.json}");
+        return 1;
+      }
+      const id = type; // first positional is the custom service id
+      if (isValidType(id)) {
+        log.err(`"${id}" is a built-in service type; choose another id.`);
+        return 1;
+      }
+      const path = rest.join(" ");
+      try {
+        const svc = readCustomService(id, path); // parse + validate now (fail fast)
+        cfg.custom[id] = path;
+        saveConfig(cfg);
+        log.ok(
+          `Added custom service ${color.cyan(id)} -> ${path} ` +
+            color.dim(`(${svc.image})`),
+        );
+      } catch (err) {
+        log.err(`Invalid custom service ${err.message}`);
+        return 1;
+      }
       return 0;
     }
     case "set": {
@@ -49,10 +82,17 @@ export function images(args) {
     }
     case "remove": {
       if (!type) {
-        log.err("Usage: bizone images remove {type}");
+        log.err("Usage: bizone images remove {type|custom-id}");
         typesHint();
         return 1;
       }
+      // A custom service id takes precedence over a built-in image override.
+      if (Object.prototype.hasOwnProperty.call(cfg.custom || {}, type)) {
+        delete cfg.custom[type];
+        saveConfig(cfg);
+        log.ok(`Removed custom service ${color.cyan(type)}`);
+        return 0;
+      }
       if (Object.prototype.hasOwnProperty.call(cfg.images, type)) {
         delete cfg.images[type];
         saveConfig(cfg);
@@ -67,7 +107,7 @@ export function images(args) {
       return 0;
     }
     default:
-      log.err("Usage: bizone images <get|set|remove> ...");
+      log.err("Usage: bizone images <get|set|remove|add> ...");
       typesHint();
       return 1;
   }

package/src/commands/resources.js

@@ -1,12 +1,22 @@
-// `bizone resources|res|r get|set|remove`
+// `bizone resources|res|r get|set|remove|import`
 
 import { existsSync } from "node:fs";
 
-import { loadConfig, saveConfig } from "../config.js";
+import { loadConfig, saveConfig, getConfigValue } from "../config.js";
+import { CONTAINERS } from "../defaults.js";
 import { resolveResourcePath } from "../resources-loader.js";
+import {
+  dockerAvailable,
+  ensureNetwork,
+  isContainerRunning,
+} from "../docker.js";
+import {
+  runCoreResourcesJob,
+  importUserResources,
+} from "../resource-import.js";
 import { color, log } from "../colors.js";
 
-export function resources(args) {
+export async function resources(args) {
   const [sub, namespace, ...rest] = args;
   const cfg = loadConfig();
 
@@ -55,8 +65,66 @@ export function resources(args) {
       }
       return 0;
     }
+    case "import":
+      // `resources import`        -> import user-configured namespaces.
+      // `resources import global` -> run ONLY the core bizone-resources job.
+      return await runImport(cfg, namespace);
     default:
-      log.err("Usage: bizone resources <get|set|remove> ...");
+      log.err("Usage: bizone resources <get|set|remove|import> ...");
       return 1;
   }
 }
+
+async function runImport(cfg, target) {
+  if (target && target !== "global") {
+    log.err("Usage: bizone resources import [global]");
+    return 1;
+  }
+  const rm = CONTAINERS["resource-manager"];
+
+  try {
+    if (target === "global") {
+      if (!dockerAvailable()) {
+        log.err("Docker does not appear to be running or installed.");
+        return 1;
+      }
+      if (!isContainerRunning(rm.containerName)) {
+        log.err(
+          `${rm.containerName} is not running; start the platform first (bizone start).`,
+        );
+        return 1;
+      }
+      const network = getConfigValue(cfg, "network_name");
+      ensureNetwork(network);
+      log.step("Running core resources import job (bizone-resources)...");
+      await runCoreResourcesJob(cfg, {
+        network,
+        imageHooks: {
+          onBeforePull: (image) =>
+            log.step(`Pulling image ${image} (this may take a while)...`),
+          onBeforeLogin: (registry) =>
+            log.step(`Authenticating to AWS ECR for ${registry}...`),
+        },
+      });
+      log.ok("Core resources import complete");
+      return 0;
+    }
+
+    // User-configured resources.
+    const count = Object.keys(cfg.resources || {}).length;
+    if (count === 0) {
+      log.warn(
+        "No resource namespaces configured. Add one with `bizone resources set {namespace} {path}`.",
+      );
+      return 0;
+    }
+    log.step(`Importing ${count} resource namespace(s)...`);
+    await importUserResources(cfg);
+    log.plain("");
+    log.plain(color.green(color.bold(`✓ Imported ${count} namespace(s)`)));
+    return 0;
+  } catch (err) {
+    log.err(err.message);
+    return 1;
+  }
+}

package/src/commands/start.js

@@ -9,33 +9,29 @@ import {
   loadContainers,
   saveContainers,
 } from "../config.js";
-import { CONTAINERS, AWS_ENV_VARS, defaultEnvFor } from "../defaults.js";
+import { CONTAINERS, AWS_ENV_VARS } from "../defaults.js";
 import {
   dockerAvailable,
   ensureNetwork,
   ensureImage,
   runDetached,
-  runBlocking,
   removeIfExists,
   mysqlReady,
   isContainerRunning,
 } from "../docker.js";
-import { waitForReady, importNamespace } from "../http.js";
-import { loadItems } from "../resources-loader.js";
+import { waitForReady } from "../http.js";
+import { loadCustomServices } from "../custom-services.js";
+import {
+  coreResourcesImported,
+  runCoreResourcesJob,
+  importUserResources,
+} from "../resource-import.js";
 import { color, log } from "../colors.js";
 
-function imageFor(cfg, type) {
-  return cfg.images[type] || CONTAINERS[type].image;
-}
-
 function hostPort(cfg, service) {
-  return getConfigValue(cfg, service.portKey);
-}
-
-// Effective env for a container type: baked-in defaults, overridden by any
-// user-set values (`bizone env set`).
-function envFor(cfg, type) {
-  return { ...defaultEnvFor(type), ...(cfg.env[type] || {}) };
+  const v = service.portKey ? getConfigValue(cfg, service.portKey) : undefined;
+  // Custom services may carry no known config key; fall back to their defaultPort.
+  return v != null ? v : service.defaultPort;
 }
 
 // A service runs if it has no enableKey (always-on) or its enableKey is true.
@@ -78,16 +74,19 @@ export async function start() {
     awsProfile,
   };
 
-  // Helper to start one service detached and record its id.
+  // Helper to start one service detached and record its id. Works for both
+  // built-in services and custom ones (which carry their own image/defaultEnv).
   const startService = (service, extraEnv = {}) => {
     removeIfExists(service.containerName); // avoid name conflicts from stale runs
-    ensureImage(imageFor(cfg, service.type), imageHooks); // pull + ECR login if needed
+    const image = cfg.images[service.type] || service.image;
+    ensureImage(image, imageHooks); // pull + ECR login if needed
+    const baseEnv = { ...(service.defaultEnv ?? {}), ...(cfg.env[service.type] || {}) };
     const id = runDetached({
       name: service.containerName,
       hostPort: hostPort(cfg, service),
       containerPort: service.containerPort,
-      image: imageFor(cfg, service.type),
-      env: { ...envFor(cfg, service.type), ...extraEnv },
+      image,
+      env: { ...baseEnv, ...extraEnv },
       volume: service.volume || null,
       network,
     });
@@ -140,28 +139,21 @@ export async function start() {
     await waitService(rm);
     log.ok("resource-manager ready");
 
-    // 3. Resources init job (blocking).
-    const resources = CONTAINERS.resources;
-    log.step("Running resources initialization job (bizone-resources)...");
-    removeIfExists(resources.containerName);
-    ensureImage(imageFor(cfg, resources.type), imageHooks);
-    await runBlocking({
-      name: resources.containerName,
-      image: imageFor(cfg, resources.type),
-      env: envFor(cfg, resources.type),
-      network,
-    });
-    log.ok("Resources initialization job complete");
-
-    // 4. Import user-configured resources.
-    const namespaces = Object.entries(cfg.resources || {});
-    if (namespaces.length > 0) {
-      const rmPort = hostPort(cfg, rm);
-      log.step(`Importing ${namespaces.length} resource namespace(s)...`);
-      for (const [namespace, path] of namespaces) {
-        const items = loadItems(path);
-        await importNamespace({ port: rmPort, namespace, items });
-        log.ok(`Imported "${namespace}" (${items.length} item(s))`);
+    // 3 + 4. Resource import — skipped entirely if the core resources were
+    // already imported (the resource-manager keeps them in its persistent DB).
+    if (await coreResourcesImported(cfg)) {
+      log.ok("Resources already imported (skipping import)");
+    } else {
+      // 3. Core resources init job (blocking).
+      log.step("Running resources initialization job (bizone-resources)...");
+      await runCoreResourcesJob(cfg, { network, imageHooks });
+      log.ok("Resources initialization job complete");
+
+      // 4. Import user-configured resources.
+      const namespaces = Object.keys(cfg.resources || {});
+      if (namespaces.length > 0) {
+        log.step(`Importing ${namespaces.length} resource namespace(s)...`);
+        await importUserResources(cfg);
       }
     }
 
@@ -197,6 +189,36 @@ export async function start() {
       ),
     );
 
+    // 7. Custom services (registered via `bizone images add`) — started last.
+    const customServices = loadCustomServices(cfg).filter((s) =>
+      isEnabled(cfg, s),
+    );
+    if (customServices.length > 0) {
+      log.step(`Starting ${customServices.length} custom service(s)...`);
+      for (const service of customServices) {
+        log.step(
+          `Starting ${service.containerName} (${service.id})` +
+            (hostPort(cfg, service) != null
+              ? ` (port ${hostPort(cfg, service)})`
+              : ""),
+        );
+        startService(service);
+      }
+      // Wait for readiness where the custom service declares how to check.
+      await Promise.all(
+        customServices.map(async (s) => {
+          if (s.readyCheck === "mysqlPing") {
+            await waitForMysql(s.containerName);
+          } else if (s.readyPath && s.readyCheck) {
+            await waitService(s);
+          } else {
+            return; // no readiness declared; assume started
+          }
+          log.ok(`${s.containerName} ready`);
+        }),
+      );
+    }
+
     log.plain("");
     log.plain(color.green(color.bold("✓ Platform is running")));
     const ui = CONTAINERS.ui;

package/src/config.js

@@ -20,7 +20,7 @@ function ensureDir() {
   }
 }
 
-const EMPTY = { config: {}, images: {}, env: {}, resources: {} };
+const EMPTY = { config: {}, images: {}, env: {}, resources: {}, custom: {} };
 
 export function loadConfig() {
   if (!existsSync(CONFIG_PATH)) {
@@ -34,6 +34,7 @@ export function loadConfig() {
       images: parsed.images || {},
       env: parsed.env || {},
       resources: parsed.resources || {},
+      custom: parsed.custom || {},
     };
   } catch (err) {
     throw new Error(`Failed to read config at ${CONFIG_PATH}: ${err.message}`);

package/src/custom-services.js

@@ -0,0 +1,89 @@
+// Additional, user-defined services registered via `bizone images add {id} {path}`.
+//
+// Each registration maps an id to a JSON file whose contents mirror the service
+// object exported by src/containers/*.js (see src/containers/mysql.js):
+//
+//   {
+//     "type": "...",            // identity used for image/env overrides (defaults to the id)
+//     "image": "repo/img:tag",  // required
+//     "containerName": "...",   // required (should start with "bizone-")
+//     "containerPort": 8080,    // optional (needed for a -p mapping)
+//     "portKey": "...",         // optional config key for the host port
+//     "defaultPort": "8080",    // optional host port fallback
+//     "enableKey": null,        // optional config key gating the service
+//     "readyPath": "/.system/status", // optional HTTP readiness path
+//     "readyCheck": "systemStatusOk", // optional: systemStatusOk | uiReadinessUp | mysqlPing
+//     "volume": { "name": "...", "mount": "..." }, // optional
+//     "defaultEnv": { "NAME": "value" }            // optional
+//   }
+//
+// Custom services start LAST (after the built-in platform is ready) and are
+// stopped by `bizone stop` like any other recorded container.
+
+import { readFileSync } from "node:fs";
+
+import { CONTAINERS } from "./defaults.js";
+import { resolveResourcePath } from "./resources-loader.js";
+
+// Readiness checks a custom service may reference (must match http.js / docker.js).
+export const KNOWN_READY_CHECKS = [
+  "systemStatusOk",
+  "uiReadinessUp",
+  "mysqlPing",
+];
+
+const BUILTIN_CONTAINER_NAMES = new Set(
+  Object.values(CONTAINERS).map((s) => s.containerName),
+);
+
+// Parse + validate one custom service definition. Throws on a bad shape.
+export function parseCustomService(id, raw) {
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`"${id}": not valid JSON (${err.message})`);
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    throw new Error(`"${id}": expected a JSON object`);
+  }
+  if (typeof obj.image !== "string" || !obj.image.trim()) {
+    throw new Error(`"${id}": missing required string field "image"`);
+  }
+  if (typeof obj.containerName !== "string" || !obj.containerName.trim()) {
+    throw new Error(`"${id}": missing required string field "containerName"`);
+  }
+  if (BUILTIN_CONTAINER_NAMES.has(obj.containerName)) {
+    throw new Error(
+      `"${id}": containerName "${obj.containerName}" collides with a built-in service`,
+    );
+  }
+  if (obj.readyCheck && !KNOWN_READY_CHECKS.includes(obj.readyCheck)) {
+    throw new Error(
+      `"${id}": unknown readyCheck "${obj.readyCheck}" (valid: ${KNOWN_READY_CHECKS.join(", ")})`,
+    );
+  }
+
+  // `type` identifies the service for image/env overrides; default to the id.
+  return { id, ...obj, type: obj.type || id };
+}
+
+// Read + parse the registration at `path` (resolved like resource paths).
+export function readCustomService(id, path) {
+  const resolved = resolveResourcePath(path);
+  const raw = readFileSync(resolved, "utf8");
+  return parseCustomService(id, raw);
+}
+
+// Load every registered custom service from config (`$.custom`).
+// Returns [{ id, ...service }]. Throws with a clear message on the first bad one.
+export function loadCustomServices(cfg) {
+  const entries = Object.entries(cfg.custom || {});
+  return entries.map(([id, path]) => {
+    try {
+      return readCustomService(id, path);
+    } catch (err) {
+      throw new Error(`Custom service ${err.message}`);
+    }
+  });
+}

package/src/docker.js

@@ -20,20 +20,27 @@ const AUTH_ERR_RE =
 // Registries we have already logged into during this process.
 const loggedInRegistries = new Set();
 
-function parseEcr(image) {
+export function parseEcr(image) {
   const m = String(image).match(ECR_RE);
   if (!m) return null;
   return { registry: m[1], region: m[2] };
 }
 
+// Build the `aws ecr get-login-password` argument list, optionally pinned to a
+// named profile. Exported for testing the aws_profile wiring.
+export function ecrPasswordArgs(region, profile) {
+  const args = ["ecr", "get-login-password", "--region", region];
+  if (profile) args.push("--profile", profile);
+  return args;
+}
+
 // Authenticate docker to the ECR registry backing `image`, using the AWS CLI.
 // No-op (returns false) for non-ECR images. Throws on failure.
 function ecrLogin(ecr, profile) {
   if (!ecr) return false;
   if (loggedInRegistries.has(ecr.registry)) return true;
 
-  const awsArgs = ["ecr", "get-login-password", "--region", ecr.region];
-  if (profile) awsArgs.push("--profile", profile);
+  const awsArgs = ecrPasswordArgs(ecr.region, profile);
 
   const pw = spawnSync("aws", awsArgs, { encoding: "utf8" });
   if (pw.status !== 0) {
@@ -142,6 +149,8 @@ export function runDetached({
     network,
     "--network-alias",
     name,
+    "--pull",
+    "always"
   ];
   if (hostPort != null && containerPort != null) {
     args.push("-p", `${hostPort}:${containerPort}`);
@@ -165,7 +174,16 @@ export function runDetached({
 // Run a container in the foreground (blocking), removing it on exit.
 export function runBlocking({ name, image, env = {}, network }) {
   return new Promise((resolve, reject) => {
-    const args = ["run", "--rm", "--name", name, "--network", network];
+    const args = [
+      "run",
+      "--rm",
+      "--name",
+      name,
+      "--network",
+      network,
+      "--pull",
+      "always"
+    ];
     for (const [k, v] of Object.entries(env)) {
       if (v === undefined || v === null || v === "") continue;
       args.push("-e", `${k}=${v}`);

package/src/http.js

@@ -51,6 +51,17 @@ export async function waitForReady({
   );
 }
 
+// Check whether a resource exists in the `.global` namespace. Returns true when
+// the endpoint responds 200 with a JSON `{ items: [...] }` of non-zero length.
+// Used to detect whether the core resources init already ran.
+export async function globalResourceExists({ port, id }) {
+  const url = `http://localhost:${port}/.global/resources?id=${encodeURIComponent(
+    id,
+  )}&expand=no`;
+  const body = await probe(url);
+  return Boolean(body && Array.isArray(body.items) && body.items.length > 0);
+}
+
 // Import a set of items into a resource-manager namespace.
 export async function importNamespace({ port, namespace, items }) {
   const url = `http://localhost:${port}/admin/${namespace}/resources`;

package/src/resource-import.js

@@ -0,0 +1,61 @@
+// Shared resource-import operations, used by both `bizone start` and
+// `bizone resources import`.
+//
+//   - core resources : the one-shot `bizone-resources` docker job, which imports
+//                       into the `.global` namespace.
+//   - user resources : the namespaces the user configured via `bizone resources set`.
+
+import { CONTAINERS, defaultEnvFor } from "./defaults.js";
+import { getConfigValue } from "./config.js";
+import { ensureImage, removeIfExists, runBlocking } from "./docker.js";
+import { importNamespace, globalResourceExists } from "./http.js";
+import { loadItems } from "./resources-loader.js";
+import { log } from "./colors.js";
+
+// A core resource that exists once the init job has run. Its presence in the
+// `.global` namespace is how we detect a prior import.
+export const CORE_INIT_PROBE_ID = "action/flow.start";
+
+function imageFor(cfg, type) {
+  return cfg.images[type] || CONTAINERS[type].image;
+}
+
+function envFor(cfg, type) {
+  return { ...defaultEnvFor(type), ...(cfg.env[type] || {}) };
+}
+
+export function rmPort(cfg) {
+  return getConfigValue(cfg, CONTAINERS["resource-manager"].portKey);
+}
+
+// True when the core resources were already imported into `.global`.
+export async function coreResourcesImported(cfg) {
+  return globalResourceExists({ port: rmPort(cfg), id: CORE_INIT_PROBE_ID });
+}
+
+// Run the one-shot `bizone-resources` job (blocking). Imports core resources
+// into `.global`. Requires the resource-manager to be running on `network`.
+export async function runCoreResourcesJob(cfg, { network, imageHooks } = {}) {
+  const job = CONTAINERS.resources;
+  removeIfExists(job.containerName);
+  ensureImage(imageFor(cfg, job.type), imageHooks);
+  await runBlocking({
+    name: job.containerName,
+    image: imageFor(cfg, job.type),
+    env: envFor(cfg, job.type),
+    network,
+  });
+}
+
+// Import every user-configured resource namespace into the resource-manager.
+// Returns the number of namespaces imported.
+export async function importUserResources(cfg) {
+  const namespaces = Object.entries(cfg.resources || {});
+  const port = rmPort(cfg);
+  for (const [namespace, path] of namespaces) {
+    const items = loadItems(path);
+    await importNamespace({ port, namespace, items });
+    log.ok(`Imported "${namespace}" (${items.length} item(s))`);
+  }
+  return namespaces.length;
+}