@metaobjectsdev/cli 1.0.1 → 1.0.3

package/src/commands/deps.ts

@@ -0,0 +1,231 @@
+// server/typescript/packages/cli/src/commands/deps.ts
+//
+// FR-023 Phase 1a — Task 14 shipped `meta deps sync` (`path` transport) and
+// `meta deps list`; Task 15 shipped `meta deps check` (this file's `runCheck`).
+import { join } from "node:path";
+import {
+  DEFAULT_METAOBJECTS_DIR,
+  discoverCollectionRoot,
+  loadConfig,
+  loadMemory,
+  resolveCollection,
+  type DependencySpec,
+  type Lock,
+} from "@metaobjectsdev/sdk";
+import { parseDepsArgs, type DepsFlags } from "../lib/args.js";
+import { log } from "../lib/log.js";
+import { emitStructured, type OutputFormat } from "../lib/format.js";
+import { reportLoadError } from "../lib/load-error.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
+import {
+  applySync,
+  checkDependencies,
+  ERR_DEPENDENCY_UPSTREAM_DRIFT,
+  formatCheckLine,
+  hash8,
+  planSync,
+  readLockOrThrow,
+} from "../lib/dependency-sync.js";
+
+/** The declared `dependencies` for the config governing `cwd` — read
+ *  DIRECTLY via `loadConfig`, never through `resolveCollection`/`Collection`:
+ *  that resolver VERIFIES the snapshot against the lock (`verifySnapshot`)
+ *  and throws `ERR_DEPENDENCY_SNAPSHOT_STALE` the moment they disagree — the
+ *  exact condition `meta deps sync` exists to fix. A project with no config
+ *  at all declares none (`resolveCollection`'s own default: no config ⇒ no
+ *  dependencies), which `discoverCollectionRoot`'s `hasConfig` already knows
+ *  without a doomed `loadConfig` call. */
+async function declaredDependencies(cwd: string): Promise<{ configDir: string; specs: readonly DependencySpec[] }> {
+  const { dir: configDir, hasConfig } = await discoverCollectionRoot(cwd);
+  if (!hasConfig) return { configDir, specs: [] };
+  const cfg = await loadConfig(join(configDir, DEFAULT_METAOBJECTS_DIR));
+  return { configDir, specs: cfg.dependencies };
+}
+
+async function runSync(configDir: string, specs: readonly DependencySpec[], flags: DepsFlags, fmt: OutputFormat): Promise<number> {
+  let lock: Lock | undefined;
+  try {
+    lock = await readLockOrThrow(configDir);
+  } catch (err) {
+    // Same convention as `depsCommand`'s `declaredDependencies` catch below: a
+    // committed project file that fails to parse is a config-class problem,
+    // exit 2 — distinct from the exit-1 a `sync` verdict failure gets.
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  let plan;
+  try {
+    plan = await planSync(configDir, specs, lock, flags.names);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+
+  let applied;
+  try {
+    applied = await applySync(configDir, plan, { dryRun: flags.dryRun });
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+
+  if (fmt === "text") {
+    for (const w of plan.warnings) log.info(w);
+    if (applied.report.length === 0) {
+      log.info("meta deps sync: nothing to do — no dependencies declared.");
+    } else {
+      for (const r of applied.report) log.info(r.line);
+    }
+  } else {
+    emitStructured(
+      {
+        warnings: plan.warnings,
+        dependencies: applied.report.map((r) => ({ name: r.name, action: r.action, message: r.line })),
+      },
+      fmt,
+    );
+  }
+
+  // A dry run wrote nothing to validate — the plan already stands for what
+  // WOULD load.
+  if (flags.dryRun) return 0;
+
+  // DESIGN §4.1's closing sentence: load the full collection once, so a sync
+  // that produces an unloadable model (a collision the plan missed because it
+  // only compares declared node LISTS, a scope that now excludes something
+  // load-bearing, …) fails in THIS command with the loader's own error,
+  // rather than surfacing on the next unrelated `meta gen`/`verify`.
+  let collection;
+  try {
+    collection = await resolveCollection(configDir);
+  } catch (err) {
+    log.error(`meta deps sync: the updated dependency set does not resolve: ${(err as Error).message}`);
+    return 1;
+  }
+  try {
+    await loadMemory(collection.configDir, collectionLoadOptions(collection));
+  } catch (err) {
+    reportLoadError(log, "meta deps sync: the updated dependency set does not load", err);
+    return 1;
+  }
+
+  return 0;
+}
+
+async function runList(configDir: string, fmt: OutputFormat): Promise<number> {
+  let lock: Lock | undefined;
+  try {
+    lock = await readLockOrThrow(configDir);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+  const entries = Object.entries(lock?.dependencies ?? {});
+
+  if (fmt === "text") {
+    if (entries.length === 0) {
+      log.info("meta deps list: no dependencies locked — run `meta deps sync`.");
+      return 0;
+    }
+    for (const [name, entry] of entries) {
+      log.info(
+        `${name} ${entry.version} ${hash8(entry.integrity)} ${entry.nodes.length} node(s) ${entry.packages.join(", ")}`,
+      );
+    }
+  } else {
+    emitStructured(
+      { dependencies: entries.map(([name, entry]) => ({ name, ...entry })) },
+      fmt,
+    );
+  }
+  return 0;
+}
+
+/**
+ * `meta deps check` (Task 15) — re-resolve each declared dependency exactly
+ * as `sync` steps 1-2 do and compare its installed artifact's TRUE hash
+ * against what `.metaobjects/deps.lock.json` pinned. Read-only: never touches
+ * the lock or the snapshot (that is `sync`'s job). A `drifted` or
+ * `unresolved` dependency fails the command — a check that cannot check must
+ * not pass.
+ */
+async function runCheck(
+  configDir: string,
+  specs: readonly DependencySpec[],
+  fmt: OutputFormat,
+): Promise<number> {
+  let lock: Lock | undefined;
+  try {
+    lock = await readLockOrThrow(configDir);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  if (specs.length === 0) {
+    if (fmt === "text") {
+      log.info("meta deps check: nothing to check — no dependencies declared.");
+    } else {
+      emitStructured({ dependencies: [] }, fmt);
+    }
+    return 0;
+  }
+
+  const results = await checkDependencies(configDir, specs, lock);
+  const failing = results.filter((r) => r.status !== "current");
+
+  if (fmt === "text") {
+    for (const r of results) log.info(formatCheckLine(r));
+    if (failing.length > 0) {
+      log.error(
+        `meta deps check: ${failing.length} of ${results.length} dependenc` +
+          `${results.length === 1 ? "y" : "ies"} drifted or unresolved (${ERR_DEPENDENCY_UPSTREAM_DRIFT}).`,
+      );
+    }
+  } else {
+    emitStructured(
+      {
+        dependencies: results.map((r) => ({ ...r, line: formatCheckLine(r) })),
+        ...(failing.length > 0 ? { code: ERR_DEPENDENCY_UPSTREAM_DRIFT } : {}),
+      },
+      fmt,
+    );
+  }
+
+  return failing.length > 0 ? 1 : 0;
+}
+
+export async function depsCommand(args: string[], cwd: string, fmt: OutputFormat): Promise<number> {
+  let flags: DepsFlags;
+  try {
+    flags = parseDepsArgs(args);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  let configDir: string;
+  let specs: readonly DependencySpec[];
+  try {
+    ({ configDir, specs } = await declaredDependencies(cwd));
+  } catch (err) {
+    // Mirrors `resolveCollection`'s own convention for a config.json that
+    // EXISTS but fails to load (malformed JSON, a schema violation): exit 2,
+    // the same code every other routed command uses for that class of
+    // failure (gen.ts, migrate.ts, docs.ts) — distinct from the exit 1 a
+    // dependency-resolution failure gets below, because this is a config
+    // problem, not a `sync` verdict.
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  switch (flags.subverb) {
+    case "sync":
+      return runSync(configDir, specs, flags, fmt);
+    case "list":
+      return runList(configDir, fmt);
+    case "check":
+      return runCheck(configDir, specs, fmt);
+  }
+}

package/src/commands/docs.ts

@@ -11,10 +11,11 @@
 // output is therefore guaranteed — it is byte-for-byte the same generator the
 // `meta gen` pipeline runs (gated by the docs conformance fixture).
 
-import { resolve as resolvePath, basename } from "node:path";
+import { resolve as resolvePath, basename, dirname } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { log } from "../lib/log.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -515,7 +516,7 @@ export async function docsCommand(
   let root;
   try {
     root = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...configLoadOptions,
     });
   } catch (err) {
@@ -860,7 +861,22 @@ async function emitSite(
   // files: a declared source directory holding no metadata yet would otherwise
   // vanish from the site's group list entirely, and `sourceDirs` could come back
   // empty where the pre-branch code always passed `<root>/metaobjects`.
-  const sourceDirs = [...collection.sourceRoots];
+  // `collection.sourceRoots` deliberately EXCLUDES dependency artifacts (sdk's
+  // collection.ts: "a dependency's artifact is not a source root"). But
+  // `generateSite` below does NOT reuse the already-loaded `collection` root —
+  // it runs its own independent `loadModel` over exactly the dirs handed to
+  // it. Without the resolved snapshot dirs appended here, a consumer that
+  // `extends` an imported abstract or `overlay: true`s an imported node — the
+  // two constructs entities.md and abstracts-and-inheritance.md recommend for
+  // this exact boundary — hits `ERR_UNRESOLVED_SUPER` / `ERR_OVERLAY_NO_TARGET`
+  // in THIS loader even though the same metadata resolves fine through
+  // `loadMemory` above. `loadModel` handles a dependency's snapshot dir
+  // natively: each holds exactly the one artifact file, which its own
+  // `.(json|ya?ml)$` file walk picks up like any other source dir.
+  const sourceDirs = [
+    ...collection.sourceRoots,
+    ...new Set(collection.dependencies.map((d) => dirname(d.artifactPath))),
+  ];
   const seenDirs = new Set(sourceDirs);
   if (promptsDir !== undefined && !existsSync(promptsDir)) {
     log.warn(`docs: --prompts dir does not exist: ${promptsDir}`);

package/src/commands/gen.ts

@@ -2,6 +2,7 @@ import { relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
 import { resolveGenConfig } from "../lib/config.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { formatGenResult, formatGenResultToon, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { formatGenResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
@@ -16,6 +17,9 @@ import {
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
+import { packageOfResolutionKey } from "@metaobjectsdev/metadata";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { Collection } from "@metaobjectsdev/sdk";
 import { reportLoadError } from "../lib/load-error.js";
 
 /**
@@ -122,7 +126,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   let metadata;
   try {
     metadata = await loadMemory(genCollection.configDir, {
-      files: genCollection.files,
+      ...collectionLoadOptions(genCollection),
       ...loadMemoryOptionsFrom(forgeConfig),
     });
   } catch (err) {
@@ -130,6 +134,19 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     return 2;
   }
 
+  // FR-023 §11.1 item 2 — refuse a positional that names ONLY objects imported
+  // from a dependency and excluded from output by the default exclusion rule.
+  // Distinct from the runner's existing "no entities matched" WARNING
+  // (runner.ts): that path covers a name matching nothing loaded at all; this
+  // one covers a name that matches something real, just not something this
+  // project generates. A name matching nothing falls through untouched — the
+  // runner's own warning still covers it.
+  const importedRefusal = refuseImportedPositional(cliConfig.entities, metadata, genCollection);
+  if (importedRefusal !== undefined) {
+    log.error(importedRefusal);
+    return 2;
+  }
+
   let result;
   try {
     result = await runGen({
@@ -145,6 +162,10 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       // passed: an unconfigured project's predicate admits everything, so this
       // is a no-op for the common case, not a behavior change.
       scope: genCollection.inScope,
+      // FR-023 §4.3 — the collection's own source files (never a dependency's
+      // snapshot artifact), so sharedModelFile() defaults its `files` selection
+      // to exactly what this project itself declares.
+      sourceFiles: genCollection.ownFiles,
       ...(cliConfig.entities.length > 0 ? { entityFilter: cliConfig.entities } : {}),
     });
   } catch (err) {
@@ -220,6 +241,45 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   return hasFailure ? 1 : 0;
 }
 
+/**
+ * FR-023 §11.1 item 2 — the error message for `meta gen <Name>` when EVERY
+ * loaded object named `<Name>` is imported from a dependency and excluded from
+ * output (imported metadata is load-only by default; only the consumer's own
+ * `scope.include` naming the package literally opts it in). Returns undefined
+ * for every other case, INCLUDING a name matching nothing at all — that stays
+ * the runner's existing "no entities matched" warning, unchanged.
+ *
+ * A bare positional is a NAME, not a fully-qualified one (`cliConfig.entities`
+ * is matched against `entity.name` elsewhere in this file the same way), so two
+ * packages declaring the same short name are both candidates; the refusal
+ * fires only when NONE of them would generate.
+ */
+function refuseImportedPositional(
+  entityNames: readonly string[],
+  metadata: MetaRoot,
+  collection: Collection,
+): string | undefined {
+  if (entityNames.length === 0) return undefined;
+  const allObjects = metadata.objects();
+  for (const name of entityNames) {
+    const matches = allObjects.filter((o) => o.name === name);
+    if (matches.length === 0) continue; // nothing loaded by this name — the runner's own warning covers it
+    const allExcludedImports = matches.every((o) => {
+      const fqn = o.resolutionKey();
+      return collection.imported(fqn) && !collection.inScope(fqn);
+    });
+    if (!allExcludedImports) continue;
+    const fqn = matches[0]!.resolutionKey();
+    const pkg = packageOfResolutionKey(fqn);
+    const dependencyName = collection.dependencies.find((d) => d.packages.includes(pkg))?.name ?? pkg;
+    return (
+      `meta gen: '${name}' (${fqn}) is imported from dependency '${dependencyName}' and is not ` +
+      `generated here — add its package to scope.include in .metaobjects/config.json to generate it`
+    );
+  }
+  return undefined;
+}
+
 /**
  * Run the advisory verify-as-teacher scan (same pass `meta verify` runs): surface
  * authored source that hand-rolls what the metadata could model. `gen` is the

package/src/commands/init.ts

@@ -1,9 +1,9 @@
 import { mkdir, writeFile, readFile, readdir, stat, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { basename, dirname } from "node:path";
+import { dirname } from "node:path";
 import { existsSync as existsSyncWrap, readFileSync as readFileSyncWrap } from "node:fs";
 import { createRequire } from "node:module";
-import { DEFAULT_CONFIG, ConfigSchema, saveConfig, PACKAGE_MANIFEST_FILE, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "@metaobjectsdev/sdk";
+import { DEFAULT_CONFIG, ConfigSchema, saveConfig, PACKAGE_MANIFEST_FILE, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, DEPS_DIR, LOCK_FILE } from "@metaobjectsdev/sdk";
 import {
   assemble, resolveAgentContextRoot, planScaffold,
   AGENT_CONTEXT_MANIFEST_PATH, type Manifest, type Stack,
@@ -85,7 +85,8 @@ const METAOBJECTS_GITIGNORE_BODY = `# The codegen merge base. The snapshot BODIE
 # These ARE meant to be tracked — keep them even if a broad pattern matches.
 !migrations/
 !config.json
-!package.meta.json
+!${DEPS_DIR}/
+!${LOCK_FILE}
 `;
 
 // A minimal root .gitignore for a fresh project — only written when none exists,
@@ -673,7 +674,6 @@ export async function init(opts: InitOptions): Promise<InitResult> {
       "metaobjects/meta.common.json",
       ".metaobjects/config.json",
       ".metaobjects/.gitignore",
-      `.metaobjects/${PACKAGE_MANIFEST_FILE}`,
     );
     result.created.push(".metaobjects/AGENTS.md", ".metaobjects/CLAUDE.md", ".claude/skills/metaobjects-*", AGENT_CONTEXT_MANIFEST_PATH);
     for (const name of SCAFFOLDED_GENERATOR_NAMES) result.created.push(`${OWNED_GENERATORS_DIR}/${name}.ts`);
@@ -703,19 +703,15 @@ export async function init(opts: InitOptions): Promise<InitResult> {
   await writeFile(join(agentDir, ".gitignore"), METAOBJECTS_GITIGNORE_BODY, "utf8");
   result.created.push(".metaobjects/.gitignore");
 
-  // .metaobjects/package.meta.json — scaffold v0.3 package manifest if absent
-  const manifestPath = join(agentDir, PACKAGE_MANIFEST_FILE);
-  if (!(await fileExists(manifestPath))) {
-    const defaultPackageName = basename(opts.cwd);
-    const manifestBody = {
-      name: defaultPackageName,
-      version: "0.1.0",
-      extends: [] as string[],
-    };
-    await writeFile(manifestPath, JSON.stringify(manifestBody, null, 2) + "\n", "utf8");
-    result.created.push(`.metaobjects/${PACKAGE_MANIFEST_FILE}`);
-  } else {
-    result.preserved.push(`.metaobjects/${PACKAGE_MANIFEST_FILE}`);
+  // .metaobjects/package.meta.json — the v0.3 prototype manifest is deprecated
+  // (nothing reads it; FR-023 metadata dependencies is its replacement), so
+  // `meta init` no longer scaffolds it. A pre-existing one is left untouched;
+  // just note the deprecation so an existing project sees it.
+  const legacyManifestPath = join(agentDir, PACKAGE_MANIFEST_FILE);
+  if (await fileExists(legacyManifestPath)) {
+    result.warnings.push(
+      `note: .metaobjects/${PACKAGE_MANIFEST_FILE} is deprecated (nothing reads it; removed in 2.0) — see docs/features/metadata-dependencies.md`,
+    );
   }
 
   await writeAgentContext(opts, result);

package/src/commands/migrate.ts

@@ -13,8 +13,10 @@ import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
 import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
-import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
+import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
+  allowOptionFor,
   buildExpectedSchemaWithProvenance,
   scopeExpectedSchema,
   scopedDiffInputs,
@@ -57,7 +59,7 @@ import {
   type WranglerRunner,
 } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
-import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
+import { ALLOW_TOKEN_MAP, tokensToAllowOptions, describeChange } from "../lib/allow.js";
 import { reportLoadError } from "../lib/load-error.js";
 
 /**
@@ -200,7 +202,8 @@ function warnIfLedgerRelocated(cwd: string, resolvedOutDir: string): void {
 }
 
 /**
- * Report what a declared `migrate.scope` left out (wording: `outOfScopeNote`).
+ * Report what this run did not govern — what a declared `migrate.scope` left out, and
+ * what a DEPENDENCY owns (wording: `exclusionNotes`).
  *
  * STDOUT in text format, STDERR otherwise. `--format json` / `--format toon` put a
  * single machine-readable document on stdout, and a prose line ahead of it breaks
@@ -209,11 +212,15 @@ function warnIfLedgerRelocated(cwd: string, resolvedOutDir: string): void {
  * (`resolveFormat`): suppressing it outright would silence the note for every
  * piped and CI run, which is most of them.
  */
-function logOutOfScope(names: readonly string[], fmt: OutputFormat): void {
-  if (names.length === 0) return;
-  const msg = outOfScopeNote("migrate", names);
-  if (fmt === "text") log.info(msg);
-  else log.warn(msg);
+function logOutOfScope(
+  names: readonly string[],
+  fromDependencies: readonly string[],
+  fmt: OutputFormat,
+): void {
+  for (const msg of exclusionNotes("migrate", names, fromDependencies)) {
+    if (fmt === "text") log.info(msg);
+    else log.warn(msg);
+  }
 }
 
 function emitStructuredError(error: string, hint: string, fmt: OutputFormat): void {
@@ -376,24 +383,20 @@ async function snapshotAbsentDrops(changes: Change[], snapPath: string): Promise
   return absent;
 }
 
-function allowFlagFor(kind: string): string {
-  switch (kind) {
-    case "drop-column": return "drop-column";
-    case "drop-table": return "drop-table";
-    case "drop-index": return "drop-index";
-    case "drop-fk": return "drop-fk";
-    case "change-column-type": return "type-change";
-    case "change-column-nullable": return "nullable-to-not-null";
-    case "change-column-default": return "drop-identity-default";
-    default: return kind;
-  }
+/** The `--allow` token that unblocks `c`. migrate-ts picks the permission by what blocked the
+ *  change (a type change can be blocked by the auto-sequence default it carries), so this only
+ *  maps that permission back to its CLI token. */
+function allowFlagFor(c: Change): string {
+  const option = allowOptionFor(c);
+  const token = Object.keys(ALLOW_TOKEN_MAP).find((t) => ALLOW_TOKEN_MAP[t] === option);
+  return token ?? c.kind;
 }
 
 function blockedToEntries(err: BlockedChangesError): BlockedEntry[] {
   return err.blocked.map((c) => ({
     kind: c.kind,
     description: describeChange(c),
-    allowFlag: allowFlagFor(c.kind),
+    allowFlag: allowFlagFor(c),
   }));
 }
 
@@ -632,7 +635,7 @@ export async function migrateCommand(
   let metadata;
   try {
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...postgresLoadOptions,
     });
   } catch (err) {
@@ -682,9 +685,9 @@ export async function migrateCommand(
     // leave the expected schema here and are suppressed on the actual side below —
     // dropping them from `expected` ALONE would propose DROP TABLE for every one of
     // them that exists in the database.
-    const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+    const scoped = scopeExpectedSchema(built, collection.inMigrateScope, importedOption(collection));
     const expected = scoped.snapshot;
-    logOutOfScope(scoped.outOfScope, fmt);
+    logOutOfScope(scoped.outOfScope, scoped.importedOutOfScope ?? [], fmt);
     let actual;
     try {
       actual = await introspect(kysely.db, kysely.dialect);
@@ -1060,7 +1063,7 @@ export async function runBaseline(
     try {
       const collection = await resolveCollection(metaRoot);
       metadata = await loadMemory(collection.configDir, {
-        files: collection.files,
+        ...collectionLoadOptions(collection),
         ...baselineLoadOptions,
       });
     } catch (err) {
@@ -1199,7 +1202,7 @@ export async function runOfflineGenerate(
   try {
     collection = await resolveCollection(metaRoot);
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...offlineLoadOptions,
     });
   } catch (err) {
@@ -1259,6 +1262,10 @@ export async function runOfflineGenerate(
       views: offlineViews,
       // Per-command scope — narrows BOTH sides of the offline diff (see planOffline).
       ...(offlineScope !== undefined ? { inScope: offlineScope } : {}),
+      // ...and the import exclusion, which planOffline threads into the SAME call.
+      // Passing it only at the direct call sites would leave the offline pipeline —
+      // the default `meta migrate` — performing no import exclusion at all.
+      ...importedOption(collection),
       allow: tokensToAllowOptions(config.allow),
       onAmbiguous: async (a) => {
         collectedAmbiguous.push(a);
@@ -1283,7 +1290,7 @@ export async function runOfflineGenerate(
   // entries); `expected` is the governed side the emitter renders against. Equal
   // for an unscoped run.
   const { diff: diffResult, nextSnapshot, expected: governedExpected } = plan;
-  logOutOfScope(plan.outOfScope, fmt);
+  logOutOfScope(plan.outOfScope, plan.importedOutOfScope ?? [], fmt);
 
   if (diffResult.blocked.length > 0) {
     log.error(`migrate: ${diffResult.blocked.length} destructive change(s) blocked; re-run with --allow <tokens>`);
@@ -1464,7 +1471,7 @@ async function runD1Migrate(
   let metadata;
   try {
     metadata = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...d1LoadOptions,
     });
   } catch (err) {
@@ -1485,9 +1492,9 @@ async function runD1Migrate(
   const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
   if (scopeRc !== undefined) return scopeRc;
   // Per-command scope — both-sided, exactly as on the Kysely path above.
-  const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+  const scoped = scopeExpectedSchema(built, collection.inMigrateScope, importedOption(collection));
   const expected = scoped.snapshot;
-  logOutOfScope(scoped.outOfScope, fmt);
+  logOutOfScope(scoped.outOfScope, scoped.importedOutOfScope ?? [], fmt);
   let actual;
   try {
     actual = await introspectD1({

package/src/commands/prompt-snapshot.ts

@@ -16,6 +16,7 @@ import { FileProvider } from "../lib/file-provider.js";
 import { snapshotPaths, unifiedDiff } from "../lib/snapshot.js";
 import { reportLoadError } from "../lib/load-error.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import { render, ESCAPERS, type RenderFormat } from "@metaobjectsdev/render";
@@ -75,7 +76,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
   let root;
   try {
     root = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...configLoadOptions,
     });
   } catch (err) {