@metaobjectsdev/sdk 0.23.2 → 0.24.1

package/dist/discovery.d.ts

@@ -0,0 +1,43 @@
+/** Exported for reuse — `collection.ts` had its own byte-identical copy
+ *  (`fileExists`); one definition, imported. */
+export declare function exists(path: string): Promise<boolean>;
+/** `exists`, narrowed to directories — `collection.ts`'s default-source probe
+ *  needs that distinction to raise its friendlier `ERR_COLLECTION_NOT_FOUND`
+ *  (a plain FILE where the default source directory should be is not a
+ *  metadata home). Lives here beside `exists` so there is one filesystem
+ *  predicate pair in the package rather than a copy per caller. */
+export declare function isDir(path: string): Promise<boolean>;
+/** Where the discovery walk stopped, and what it found there. */
+export interface DiscoveredRoot {
+    /** The project root the walk settled on. Always absolute; falls back to the
+     *  resolved start directory when the walk found no marker at all. */
+    readonly dir: string;
+    /** Whether `dir` carries `.metaobjects/config.json`. False only on the
+     *  no-marker fallback, where the DEFAULT sources apply. */
+    readonly hasConfig: boolean;
+}
+/**
+ * Walk up from `startDir` for the nearest project root — a directory holding
+ * `.metaobjects/config.json`, and nothing else (see the file header). The walk
+ * stops after examining a directory that contains `.git`, so a monorepo can
+ * never silently adopt a parent checkout's configuration.
+ *
+ * Never fails: with no config anywhere below the boundary it reports the
+ * resolved `startDir` with `hasConfig: false`, which is what
+ * `resolveCollection` turns into either the default source or
+ * `ERR_COLLECTION_NOT_FOUND`.
+ */
+export declare function discoverCollectionRoot(startDir: string): Promise<DiscoveredRoot>;
+/**
+ * The directory whose configuration governs a run started in `startDir` — the
+ * `dir` half of {@link discoverCollectionRoot}.
+ *
+ * Exists as its own export for the callers that must NOT require metadata to
+ * exist: `meta migrate apply-pending` and `--rollback` replay committed SQL and
+ * load no model at all, so they resolve their `.metaobjects/` directory through
+ * this rather than through `resolveCollection`. Sharing the walk is the point —
+ * a second "find the project root" implementation is how the migrations
+ * directory and the metadata directory come to disagree.
+ */
+export declare function resolveConfigDir(startDir: string): Promise<string>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAkCA;gDACgD;AAChD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;;;mEAImE;AACnE,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM1D;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B;yEACqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;+DAC2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAetF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE"}

package/dist/discovery.js

@@ -0,0 +1,100 @@
+// server/typescript/packages/sdk/src/discovery.ts
+//
+// Phase-1 metadata-source-resolution — nearest-ancestor collection discovery.
+//
+// Walks up from a starting directory to find the nearest directory that IS a
+// project root. This is what makes a CLI *contextual*: run it inside an app in
+// a monorepo and it finds that app's configuration rather than the repo root's.
+//
+// Three properties are load-bearing.
+//
+// 1. **One marker.** A directory is a project root when it carries
+//    `.metaobjects/config.json`, and on no other evidence. A directory that
+//    merely *holds* metadata is not a project boundary: where metadata lives is
+//    the `sources` key's answer, and `metaobjects/` is only that key's default
+//    value. Stopping on a bare `metaobjects/` directory would put a second
+//    definition of "where metadata lives" back into the walk — the exact
+//    duplication `resolveCollection` exists to be the only instance of — and it
+//    would ignore a project whose config points its `sources` somewhere else
+//    entirely. See design §4.6.1.
+// 2. **Nearest wins** — the walk returns on the FIRST directory carrying the
+//    marker, so a config in a subdirectory beats one in an ancestor.
+// 3. **The walk stops at a repository boundary** (`.git`), so a monorepo
+//    checkout can never silently adopt a *parent checkout's* configuration. The
+//    marker check runs BEFORE the `.git` check within each directory —
+//    reversed, a root-level project (where `.git` also lives) would be
+//    unreachable from any subdirectory, since the boundary would stop the walk
+//    one directory too early.
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_FILE } from "./config.js";
+import { DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+const GIT_DIR = ".git";
+/** Exported for reuse — `collection.ts` had its own byte-identical copy
+ *  (`fileExists`); one definition, imported. */
+export async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `exists`, narrowed to directories — `collection.ts`'s default-source probe
+ *  needs that distinction to raise its friendlier `ERR_COLLECTION_NOT_FOUND`
+ *  (a plain FILE where the default source directory should be is not a
+ *  metadata home). Lives here beside `exists` so there is one filesystem
+ *  predicate pair in the package rather than a copy per caller. */
+export async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk up from `startDir` for the nearest project root — a directory holding
+ * `.metaobjects/config.json`, and nothing else (see the file header). The walk
+ * stops after examining a directory that contains `.git`, so a monorepo can
+ * never silently adopt a parent checkout's configuration.
+ *
+ * Never fails: with no config anywhere below the boundary it reports the
+ * resolved `startDir` with `hasConfig: false`, which is what
+ * `resolveCollection` turns into either the default source or
+ * `ERR_COLLECTION_NOT_FOUND`.
+ */
+export async function discoverCollectionRoot(startDir) {
+    const start = resolve(startDir);
+    let dir = start;
+    for (;;) {
+        if (await exists(join(dir, DEFAULT_METAOBJECTS_DIR, CONFIG_FILE))) {
+            return { dir, hasConfig: true };
+        }
+        // Boundary check AFTER the marker check: a repo-root project (sharing its
+        // directory with `.git`) is still findable from any subdirectory.
+        if (await exists(join(dir, GIT_DIR)))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { dir: start, hasConfig: false };
+}
+/**
+ * The directory whose configuration governs a run started in `startDir` — the
+ * `dir` half of {@link discoverCollectionRoot}.
+ *
+ * Exists as its own export for the callers that must NOT require metadata to
+ * exist: `meta migrate apply-pending` and `--rollback` replay committed SQL and
+ * load no model at all, so they resolve their `.metaobjects/` directory through
+ * this rather than through `resolveCollection`. Sharing the walk is the point —
+ * a second "find the project root" implementation is how the migrations
+ * directory and the metadata directory come to disagree.
+ */
+export async function resolveConfigDir(startDir) {
+    return (await discoverCollectionRoot(startDir)).dir;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,qCAAqC;AACrC,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,yEAAyE;AACzE,gFAAgF;AAChF,6EAA6E;AAC7E,kCAAkC;AAClC,6EAA6E;AAC7E,qEAAqE;AACrE,yEAAyE;AACzE,gFAAgF;AAChF,uEAAuE;AACvE,uEAAuE;AACvE,+EAA+E;AAC/E,8BAA8B;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,OAAO,GAAG,MAAM,CAAC;AAEvB;gDACgD;AAChD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;mEAImE;AACnE,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,SAAS,CAAC;QACR,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,uBAAuB,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClC,CAAC;QACD,0EAA0E;QAC1E,kEAAkE;QAClE,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAAE,MAAM;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IACrD,OAAO,CAAC,MAAM,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -12,8 +12,17 @@ export { ConfigSchema, DEFAULT_CONFIG, loadConfig, saveConfig, AllowTokenEnum }
 export type { Config } from "./config.js";
 export { FORGE_TYPE_DECISION, FORGE_TYPE_PRINCIPLE, FORGE_TYPE_CONVENTION, FORGE_TYPE_GLOSSARY, FORGE_TYPE_FAILURE, FORGE_TYPES, FORGE_DECISION_SUBTYPES, FORGE_PRINCIPLE_SUBTYPES, FORGE_CONVENTION_SUBTYPES, FORGE_GLOSSARY_SUBTYPES, FORGE_FAILURE_SUBTYPES, FORGE_ATTR_CONFIDENCE, FORGE_ATTR_SOURCE, FORGE_ATTR_CAPTURED_AT, FORGE_ATTR_LAST_VALIDATED_COMMIT, FORGE_ATTR_PRIMARY_LOCATION, FORGE_ATTR_OCCURRENCES, FORGE_ATTR_RATIONALE, FORGE_ATTR_ALTERNATIVES, FORGE_ATTR_SCOPE, FORGE_ATTR_STATEMENT, FORGE_ATTR_ENFORCEMENT, FORGE_ATTR_PATTERN_DESCRIPTION, FORGE_ATTR_EXAMPLES, FORGE_ATTR_COUNTER_EXAMPLES, FORGE_ATTR_APPLIES_TO, FORGE_ATTR_TERM, FORGE_ATTR_SYNONYMS, FORGE_ATTR_DEFINITION, FORGE_ATTR_CODE_ANCHORS, FORGE_ATTR_SEE_ALSO, FORGE_ATTR_WHAT_WAS_TRIED, FORGE_ATTR_WHY_IT_FAILED, FORGE_ATTRS, registerForgeTypes, forgeTypesProvider, } from "./forge-types.js";
 export type { ForgeType, ForgeAttr } from "./forge-types.js";
-export { loadMemory, defaultLoadMemoryProviders, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, } from "./memory.js";
+export { loadMemory, defaultLoadMemoryProviders } from "./memory.js";
 export type { LoadMemoryOptions } from "./memory.js";
+export { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+export { compileScope, matchesScope } from "./scope.js";
+export type { Scope, CompiledScope } from "./scope.js";
+export { resolveSources, resolveSpecPath, orderedPathSpecs, DEFAULT_SOURCES } from "./sources.js";
+export type { SourceSpec, ResolvedSource } from "./sources.js";
+export { discoverCollectionRoot, resolveConfigDir } from "./discovery.js";
+export type { DiscoveredRoot } from "./discovery.js";
+export { resolveCollection } from "./collection.js";
+export type { Collection } from "./collection.js";
 export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
 export type { Workspace, WorkspacePackage } from "./workspace.js";
 export { PackageManifestSchema, readPackageManifest, resolveMetaobjectsPackage, PACKAGE_MANIFEST_FILE, } from "./package.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACnG,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,EAEL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB,EAEtB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,WAAW,EAEX,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK7D,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtF,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAOlE,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -24,10 +24,23 @@ FORGE_DECISION_SUBTYPES, FORGE_PRINCIPLE_SUBTYPES, FORGE_CONVENTION_SUBTYPES, FO
 FORGE_ATTR_CONFIDENCE, FORGE_ATTR_SOURCE, FORGE_ATTR_CAPTURED_AT, FORGE_ATTR_LAST_VALIDATED_COMMIT, FORGE_ATTR_PRIMARY_LOCATION, FORGE_ATTR_OCCURRENCES, FORGE_ATTR_RATIONALE, FORGE_ATTR_ALTERNATIVES, FORGE_ATTR_SCOPE, FORGE_ATTR_STATEMENT, FORGE_ATTR_ENFORCEMENT, FORGE_ATTR_PATTERN_DESCRIPTION, FORGE_ATTR_EXAMPLES, FORGE_ATTR_COUNTER_EXAMPLES, FORGE_ATTR_APPLIES_TO, FORGE_ATTR_TERM, FORGE_ATTR_SYNONYMS, FORGE_ATTR_DEFINITION, FORGE_ATTR_CODE_ANCHORS, FORGE_ATTR_SEE_ALSO, FORGE_ATTR_WHAT_WAS_TRIED, FORGE_ATTR_WHY_IT_FAILED, FORGE_ATTRS, 
 // Registration helper + provider
 registerForgeTypes, forgeTypesProvider, } from "./forge-types.js";
-// Memory loader — read metaobjects/ into a MetaData tree
-// (workspace-aware: walks extends: deps via pnpm-workspace.yaml or
-//  package.json workspaces field if present)
-export { loadMemory, defaultLoadMemoryProviders, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR, } from "./memory.js";
+// Memory loader — read a project's resolved metadata into a MetaData tree.
+// Where those files come from is `resolveCollection`'s decision (below), which
+// `loadMemory` calls when the caller supplies no explicit file set.
+export { loadMemory, defaultLoadMemoryProviders } from "./memory.js";
+// Default project layout — the DEFAULT value of `sources` (applied by
+// `resolveCollection` alone) and the fixed directory holding the config that
+// declares them. Exported for `meta init`, which SCAFFOLDS that layout.
+export { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+// Scope — output filter over fully-qualified node names
+export { compileScope, matchesScope } from "./scope.js";
+// Source resolution — a declared source SET to a canonically-sorted file list
+export { resolveSources, resolveSpecPath, orderedPathSpecs, DEFAULT_SOURCES } from "./sources.js";
+// Discovery — nearest-ancestor project root (a `.metaobjects/config.json`,
+// the only marker), bounded by the repo root
+export { discoverCollectionRoot, resolveConfigDir } from "./discovery.js";
+// Collection — the single authority on where a project's metadata lives
+export { resolveCollection } from "./collection.js";
 // Workspace discovery — finds peer metadata packages in a monorepo
 export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
 // Package manifest — the v0.3 package.meta.json model. Three-field manifest

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,UAAU;AACV,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,QAAQ;AACR,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzD,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGnG,0EAA0E;AAC1E,0EAA0E;AAC1E,gCAAgC;AAChC,OAAO;AACL,aAAa;AACb,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW;AACX,WAAW;AACX,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB;AACtB,kBAAkB;AAClB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,WAAW;AACX,iCAAiC;AACjC,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,yDAAyD;AACzD,mEAAmE;AACnE,6CAA6C;AAC7C,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAGrB,mEAAmE;AACnE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGtF,4EAA4E;AAC5E,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,uBAAuB;AACvB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAGtB,uEAAuE;AACvE,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,UAAU;AACV,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,QAAQ;AACR,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzD,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGnG,0EAA0E;AAC1E,0EAA0E;AAC1E,gCAAgC;AAChC,OAAO;AACL,aAAa;AACb,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW;AACX,WAAW;AACX,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB;AACtB,kBAAkB;AAClB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,8BAA8B,EAC9B,mBAAmB,EACnB,2BAA2B,EAC3B,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,wBAAwB,EACxB,WAAW;AACX,iCAAiC;AACjC,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,2EAA2E;AAC3E,+EAA+E;AAC/E,oEAAoE;AACpE,OAAO,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGrE,sEAAsE;AACtE,6EAA6E;AAC7E,wEAAwE;AACxE,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,wDAAwD;AACxD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGxD,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGlG,2EAA2E;AAC3E,6CAA6C;AAC7C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG1E,wEAAwE;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD,mEAAmE;AACnE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGtF,4EAA4E;AAC5E,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,uBAAuB;AACvB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAGtB,uEAAuE;AACvE,cAAc,0BAA0B,CAAC"}

package/dist/memory.d.ts

@@ -1,15 +1,4 @@
 import { type MetaDataTypeProvider, type MetaRoot } from "@metaobjectsdev/metadata";
-/**
- * Default directory name (relative to project root) where metadata JSON files
- * are scanned. Scaffold via `meta init`; the directory is committed to git.
- */
-export declare const DEFAULT_METADATA_DIR = "metaobjects";
-/**
- * Default directory name (relative to project root) for MetaObjects' own
- * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
- * Scaffold via `meta init`; most contents are committed to git.
- */
-export declare const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
 /**
  * Options for {@link loadMemory}. Consumers can supply additional
  * {@link MetaDataTypeProvider}s to extend the metamodel with their own
@@ -36,6 +25,31 @@ export interface LoadMemoryOptions {
      * the `meta verify` command opts in to `true` (strict-by-default, #96).
      */
     strict?: boolean;
+    /**
+     * An already-resolved, absolute metadata file list — normally
+     * `resolveCollection(...).files`. When supplied, `loadMemory` loads exactly
+     * these files and resolves nothing itself.
+     *
+     * Omitting it is not a different WAY of finding metadata, only a different
+     * place the same resolution happens: `loadMemory` then calls
+     * `resolveCollection(repoRoot)` itself. Passing it saves the second
+     * resolution when the caller already holds a collection (every routed CLI
+     * command does) and lets a caller load a file set it computed some other
+     * way; it can no longer diverge from what the config declares.
+     */
+    files?: readonly string[];
+    /**
+     * MetaObjects-shipped library packages to load ALONGSIDE the project's own files
+     * (e.g. `["ai"]` for `metaobjects::ai::LlmCallBase`). Prepended, so an
+     * `extends: "metaobjects::ai::LlmCallBase"` in project metadata resolves.
+     *
+     * Opt-in rather than always-on: a library package registers real top-level nodes, and
+     * a project that never references one should not have them appear in its model, its
+     * generated output or its docs. Without this the CLI could not load the metadata that
+     * shipped generators like `trace-helper` exist to consume, so the generator was
+     * reachable from the command line while its input was not (#333).
+     */
+    libraries?: readonly string[];
 }
 /** Default provider bundle threaded by {@link loadMemory} when no options
  *  override is supplied. Exposed for tests/inspection; callers shouldn't need
@@ -43,10 +57,15 @@ export interface LoadMemoryOptions {
  *  composes `[...defaultLoadMemoryProviders, mine]` automatically. */
 export declare const defaultLoadMemoryProviders: readonly MetaDataTypeProvider[];
 /**
- * Load all metadata files from `<repoRoot>/metaobjects/` into a single
- * MetaData. If `<repoRoot>/.meta/package.meta.json` declares `extends:` deps
- * and a workspace can be discovered (pnpm-workspace.yaml or package.json
- * workspaces), peer packages are loaded too in topological dep-first order.
+ * Load a project's metadata into a single MetaData tree.
+ *
+ * Which files those are is `resolveCollection`'s decision, never this
+ * function's: with no {@link LoadMemoryOptions.files} it calls
+ * `resolveCollection(repoRoot)` — nearest-ancestor `.metaobjects/config.json`,
+ * then that config's declared `sources`, falling back to the default source
+ * directory only when a project declares none. `loadMemory` names no directory
+ * of its own, so a caller cannot end up loading from somewhere the rest of the
+ * toolchain does not.
  *
  * Excludes `_pending/`. Registers metaobjects core types plus Meta Forge's
  * descriptive top-level types (decision, principle, etc.) so mixed content
@@ -54,11 +73,15 @@ export declare const defaultLoadMemoryProviders: readonly MetaDataTypeProvider[]
  * {@link LoadMemoryOptions.providers}) are composed AFTER the defaults so
  * they may depend on core/forge ids.
  *
- * Throws if `metaobjects/` doesn't exist (callers should run `meta init`).
+ * Throws `ERR_COLLECTION_NOT_FOUND` when nothing resolves (callers should run
+ * `meta init`), unless `options.files` is supplied.
  *
- * @param repoRoot The project's working-directory root (e.g. process.cwd()).
- *   `loadMemory` resolves `metaobjects/` and (if workspace-aware) the
- *   transitive `extends:` graph automatically.
+ * @param repoRoot Where resolution STARTS — the working directory, typically
+ *   `process.cwd()`. The walk goes up from here for the governing config, so
+ *   this need not be the project root itself.
+ *   **Ignored entirely when `options.files` is supplied**: that list is already
+ *   resolved, so nothing reads this path. Every routed CLI command passes both,
+ *   and the argument is inert at all of them.
  * @param options Optional {@link LoadMemoryOptions} — supply additional
  *   providers or replace the default bundle entirely.
  */

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;sEAGsE;AACtE,eAAO,MAAM,0BAA0B,EAAE,SAAS,oBAAoB,EAGrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAgCnB"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAKlC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED;;;sEAGsE;AACtE,eAAO,MAAM,0BAA0B,EAAE,SAAS,oBAAoB,EAGrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAiDnB"}

package/dist/memory.js

@@ -1,20 +1,7 @@
-import { join } from "node:path";
-import { readdir, stat } from "node:fs/promises";
 import { composeRegistry, coreProviders, MetaDataLoader, } from "@metaobjectsdev/metadata";
 import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolveCollection } from "./collection.js";
 import { forgeTypesProvider } from "./forge-types.js";
-import { discoverWorkspace, resolveExtendsOrder } from "./workspace.js";
-/**
- * Default directory name (relative to project root) where metadata JSON files
- * are scanned. Scaffold via `meta init`; the directory is committed to git.
- */
-export const DEFAULT_METADATA_DIR = "metaobjects";
-/**
- * Default directory name (relative to project root) for MetaObjects' own
- * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
- * Scaffold via `meta init`; most contents are committed to git.
- */
-export const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
 /** Default provider bundle threaded by {@link loadMemory} when no options
  *  override is supplied. Exposed for tests/inspection; callers shouldn't need
  *  to spread this manually — `loadMemory(root, { providers: [mine] })`
@@ -24,10 +11,15 @@ export const defaultLoadMemoryProviders = [
     forgeTypesProvider,
 ];
 /**
- * Load all metadata files from `<repoRoot>/metaobjects/` into a single
- * MetaData. If `<repoRoot>/.meta/package.meta.json` declares `extends:` deps
- * and a workspace can be discovered (pnpm-workspace.yaml or package.json
- * workspaces), peer packages are loaded too in topological dep-first order.
+ * Load a project's metadata into a single MetaData tree.
+ *
+ * Which files those are is `resolveCollection`'s decision, never this
+ * function's: with no {@link LoadMemoryOptions.files} it calls
+ * `resolveCollection(repoRoot)` — nearest-ancestor `.metaobjects/config.json`,
+ * then that config's declared `sources`, falling back to the default source
+ * directory only when a project declares none. `loadMemory` names no directory
+ * of its own, so a caller cannot end up loading from somewhere the rest of the
+ * toolchain does not.
  *
  * Excludes `_pending/`. Registers metaobjects core types plus Meta Forge's
  * descriptive top-level types (decision, principle, etc.) so mixed content
@@ -35,11 +27,15 @@ export const defaultLoadMemoryProviders = [
  * {@link LoadMemoryOptions.providers}) are composed AFTER the defaults so
  * they may depend on core/forge ids.
  *
- * Throws if `metaobjects/` doesn't exist (callers should run `meta init`).
+ * Throws `ERR_COLLECTION_NOT_FOUND` when nothing resolves (callers should run
+ * `meta init`), unless `options.files` is supplied.
  *
- * @param repoRoot The project's working-directory root (e.g. process.cwd()).
- *   `loadMemory` resolves `metaobjects/` and (if workspace-aware) the
- *   transitive `extends:` graph automatically.
+ * @param repoRoot Where resolution STARTS — the working directory, typically
+ *   `process.cwd()`. The walk goes up from here for the governing config, so
+ *   this need not be the project root itself.
+ *   **Ignored entirely when `options.files` is supplied**: that list is already
+ *   resolved, so nothing reads this path. Every routed CLI command passes both,
+ *   and the argument is inert at all of them.
  * @param options Optional {@link LoadMemoryOptions} — supply additional
  *   providers or replace the default bundle entirely.
  */
@@ -56,87 +52,34 @@ export async function loadMemory(repoRoot, options) {
         providers = [...defaultLoadMemoryProviders, ...extra];
     }
     const registry = composeRegistry(providers);
-    // Collect all metadata file paths to load. Order matters for the parser's
-    // deferred-resolution pass (it parses in array order, then resolves supers
-    // against the merged tree afterwards) — dep packages first, current last.
-    const paths = await collectMetadataPaths(repoRoot);
+    // Both arms are `resolveCollection`'s answer — one already computed by the
+    // caller, one computed here. There is no third way to find metadata, and
+    // that is the whole of this line's design: the previous no-`files` arm
+    // scanned `<repoRoot>/<default dir>` directly, so a caller that copied the
+    // routed shape but forgot `files` silently loaded from a directory the
+    // project's config may never have mentioned.
+    const paths = options?.files !== undefined
+        ? [...options.files]
+        : [...(await resolveCollection(repoRoot)).files];
     const loader = new MetaDataLoader({
         registry,
         ...(options?.strict === true ? { strict: true } : {}),
     });
-    const result = await loader.load(paths.map((p) => new FileSource(p)));
+    // Library sources are imported lazily and only when asked for — the same reason
+    // `MetaDataLoader.fromDirectory` does it. `library-sources.ts` reads `node:fs`, so a
+    // static import from a root-reachable module drags Node built-ins into every consumer's
+    // graph; that is the #287 bundle defect, and the `./library` subpath exists for exactly
+    // the reason `./constants` does. Prepended, so a project's `extends` onto a
+    // library-shipped abstract base resolves — super resolution is order-independent, but
+    // prepending is the deterministic choice and matches `fromDirectory`.
+    const libSources = options?.libraries !== undefined && options.libraries.length > 0
+        ? (await import("@metaobjectsdev/metadata/library")).librarySources([...options.libraries])
+        : [];
+    const result = await loader.load([...libSources, ...paths.map((p) => new FileSource(p))]);
     if (result.errors.length > 0) {
         const first = result.errors[0];
         throw first;
     }
     return result.root;
 }
-// Dep packages' metaobjects/ files first (topological order), then current.
-async function collectMetadataPaths(repoRoot) {
-    const currentMetaDir = join(repoRoot, ".meta");
-    const ws = await discoverWorkspace(repoRoot);
-    // Workspace path: walk extends, load dep metaobjects/ dirs first
-    if (ws !== undefined) {
-        const currentPkg = ws.packages.find((p) => p.metaDir === currentMetaDir);
-        if (currentPkg !== undefined && currentPkg.manifest.extends.length > 0) {
-            const ordered = resolveExtendsOrder(ws, currentMetaDir);
-            const paths = [];
-            for (const pkg of ordered) {
-                // Each workspace package's metadata lives alongside its .meta/ dir
-                const pkgRoot = join(pkg.metaDir, "..");
-                paths.push(...(await listMetadataFiles(join(pkgRoot, DEFAULT_METADATA_DIR))));
-            }
-            return paths;
-        }
-    }
-    // Single-package path: scan metaobjects/ at the project root
-    return listMetadataFiles(join(repoRoot, DEFAULT_METADATA_DIR));
-}
-/**
- * Recursively list metadata files (*.json, *.yaml, *.yml) under a directory,
- * excluding _pending/ at any level. Subdirectories (e.g. projections/) are
- * walked depth-first. Files within a directory are sorted alphabetically for
- * deterministic load order; subdirectories are visited after files at the
- * same level.
- *
- * Format selection (parsing) happens downstream in `FileSource` from
- * `@metaobjectsdev/metadata`, which infers the parser from file extension.
- */
-async function listMetadataFiles(dir) {
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch (err) {
-        throw new Error(`loadMemory: cannot read ${dir}: ${err.message}`);
-    }
-    const paths = [];
-    const subdirs = [];
-    // #188: sort the raw `readdir` entries so file order is deterministic across
-    // runtimes/filesystems (Node vs Bun return different `readdir` orders), matching
-    // this function's docstring and the metadata package's own `DirectorySource`.
-    // (Resolution is now order-INDEPENDENT — super-resolve.ts #188 — so this is the
-    // deterministic-enumeration FLOOR, not the fix; it keeps every derived artifact
-    // that preserves declaration order, e.g. serialization, stable across runtimes.)
-    for (const entry of [...entries].sort()) {
-        if (entry === "_pending")
-            continue;
-        const full = join(dir, entry);
-        const s = await stat(full);
-        if (s.isDirectory()) {
-            subdirs.push(full);
-        }
-        else if (s.isFile() && isMetadataFile(entry)) {
-            paths.push(full);
-        }
-    }
-    // Recurse into subdirectories after collecting files at this level
-    for (const sub of subdirs.sort()) {
-        paths.push(...(await listMetadataFiles(sub)));
-    }
-    return paths;
-}
-function isMetadataFile(name) {
-    return name.endsWith(".json") || name.endsWith(".yaml") || name.endsWith(".yml");
-}
 //# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,cAAc,GAGf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAuDtD;;;sEAGsE;AACtE,MAAM,CAAC,MAAM,0BAA0B,GAAoC;IACzE,GAAG,aAAa;IAChB,kBAAkB;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,OAA2B;IAE3B,MAAM,KAAK,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IACvC,IAAI,SAA0C,CAAC;IAC/C,IAAI,OAAO,EAAE,eAAe,KAAK,IAAI,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,oFAAoF,CACrF,CAAC;QACJ,CAAC;QACD,SAAS,GAAG,KAAK,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,CAAC,GAAG,0BAA0B,EAAE,GAAG,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAE5C,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,uEAAuE;IACvE,6CAA6C;IAC7C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,KAAK,SAAS;QACxC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;QACpB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,QAAQ;QACR,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;IAEH,gFAAgF;IAChF,qFAAqF;IACrF,wFAAwF;IACxF,wFAAwF;IACxF,4EAA4E;IAC5E,sFAAsF;IACtF,sEAAsE;IACtE,MAAM,UAAU,GACd,OAAO,EAAE,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QAC9D,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,kCAAkC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAC3F,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1F,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;QAChC,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/metadata-files.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The DEFAULT value of `sources` — the directory scanned when
+ * `.metaobjects/config.json` declares no sources. Scaffold via `meta init`;
+ * the directory is committed to git.
+ *
+ * **A default, and nothing else.** No read path may assume a directory of this
+ * name exists or is where metadata lives: that question is answered by
+ * `resolveCollection`, which applies this constant exactly once (via
+ * `DEFAULT_SOURCES` in `sources.ts`) when a project declares nothing. A
+ * project that declares `sources` may put its metadata anywhere, and every
+ * command follows the config. `test/no-hardcoded-metadata-dir.test.ts` is the
+ * enforcer.
+ */
+export declare const DEFAULT_METADATA_DIR = "metaobjects";
+/**
+ * Default directory name (relative to project root) for MetaObjects' own
+ * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
+ * Scaffold via `meta init`; most contents are committed to git.
+ *
+ * Unlike {@link DEFAULT_METADATA_DIR} this one IS a fixed convention — it is
+ * where the config that answers "where is the metadata?" lives, so it cannot
+ * itself be configured.
+ */
+export declare const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
+/** Recognized metadata file extensions, matched case-insensitively — mirrors
+ *  `DirectorySource` in `@metaobjectsdev/metadata`, which checks
+ *  `extname().toLowerCase()`. The single definition every metadata-file
+ *  walker in this package uses — and since `resolveSources` (`sources.ts`)
+ *  calls {@link listMetadataFiles} outright rather than keeping a second
+ *  recursive walk of its own, there is exactly one walker to keep honest. */
+export declare const METADATA_EXTENSIONS: Set<string>;
+export declare function isMetadataFile(name: string): boolean;
+/**
+ * Recursively list metadata files (*.json, *.yaml, *.yml, matched
+ * case-insensitively — see `isMetadataFile` above) under a directory,
+ * excluding _pending/ at any level. Subdirectories (e.g. projections/) are
+ * walked depth-first. Files within a directory are sorted alphabetically for
+ * deterministic load order; subdirectories are visited AFTER the files at the
+ * same level.
+ *
+ * That per-level rule is a contract, not an implementation detail. This is the
+ * order production has always handed the loader, and declaration order survives
+ * into generated output: `codegen-ts`'s barrel emits from `root.objects()`
+ * order, and so do the shared `enums.ts`, `meta docs` page ordering and `meta
+ * export`'s `canonicalSerialize` sibling order. A flat lexicographic sort of
+ * absolute paths is NOT the same list — it disagrees whenever a subdirectory
+ * name sorts before a sibling file (`common/` before `meta.users.json`) — so
+ * `resolveSources` calls this function rather than re-walking and re-sorting.
+ * Pinned by `test/source-order.test.ts`.
+ *
+ * Exported for that gate and for `sources.ts`; not re-exported from the package
+ * index — `resolveCollection` is the public door.
+ *
+ * An entry whose `stat` fails (a dangling symlink, a TOCTOU removal between
+ * `readdir` and `stat`, an EACCES entry) is SKIPPED, matching `DirectorySource`
+ * in `@metaobjectsdev/metadata`, which this walk otherwise mirrors. A failure to
+ * read the directory itself still throws — that is the "you have no metadata
+ * here" case callers report.
+ *
+ * A symlink CYCLE (e.g. `metaobjects/link -> ..`) is a loud error rather than
+ * unbounded recursion — see {@link listMetadataFilesGuarded}.
+ *
+ * Format selection (parsing) happens downstream in `FileSource` from
+ * `@metaobjectsdev/metadata`, which infers the parser from file extension.
+ */
+export declare function listMetadataFiles(dir: string): Promise<string[]>;
+//# sourceMappingURL=metadata-files.d.ts.map

package/dist/metadata-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-files.d.ts","sourceRoot":"","sources":["../src/metadata-files.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD;;;;;6EAK6E;AAC7E,eAAO,MAAM,mBAAmB,aAAsC,CAAC;AAEvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEtE"}