@metaobjectsdev/sdk 0.5.0-rc.1

package/dist/package.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * The package.meta.json schema. Authoring this is the one-time cost of
+ * defining a metadata package; subsequent edits should be rare.
+ */
+export declare const PackageManifestSchema: z.ZodObject<{
+    /**
+     * Canonical name of the package in the language's native package manager.
+     * Conventionally `@scope/name` (npm-style) for TS, but bare names also
+     * work. Each language's package config (pom.xml, .csproj, pyproject.toml)
+     * uses its own native field for this — only TS uses `name` here.
+     */
+    name: z.ZodString;
+    /** Semver version of this package. */
+    version: z.ZodString;
+    /**
+     * Optional cross-language canonical ref for this package, used inside
+     * metadata files (extends:, super:) and for cross-language consumption.
+     * If omitted, derived from `name` via a simple rule: `@scope/name` →
+     * `scope::name` (strip @, replace `/` with `::`). Hyphens stay as-is in
+     * the auto-derived form — for hierarchical naming users declare this
+     * field explicitly.
+     *
+     * Per v0.3 strategy doc §8.2.
+     */
+    metaobjectsPackage: z.ZodOptional<z.ZodString>;
+    /**
+     * Other packages whose metadata trees this package extends. Each entry is
+     * a package name; the loader resolves it to the matching peer package.
+     * Empty/omitted means this package has no upstream dependencies.
+     */
+    extends: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+    extends: string[];
+    metaobjectsPackage?: string | undefined;
+}, {
+    name: string;
+    version: string;
+    metaobjectsPackage?: string | undefined;
+    extends?: string[] | undefined;
+}>;
+export type PackageManifest = z.infer<typeof PackageManifestSchema>;
+export declare const PACKAGE_MANIFEST_FILE = "package.meta.json";
+/**
+ * Read a package.meta.json from a given .meta/ root, if present.
+ * Returns undefined when the file isn't there — packages are optional in
+ * v0.3 v0.1 (loadMemory still works for single-package usage without one,
+ * and forge init scaffolds one but doesn't enforce its presence).
+ */
+export declare function readPackageManifest(metaDir: string): Promise<PackageManifest | undefined>;
+/**
+ * Return the canonical metaobjects package ref for a manifest. Uses the
+ * explicit `metaobjectsPackage` field if set; otherwise derives from `name`
+ * via the simple rule: `@scope/foo-bar` → `scope::foo-bar` (strip @,
+ * replace `/` with `::`, leave hyphens). For hierarchical or non-trivial
+ * naming users declare `metaobjectsPackage` explicitly.
+ *
+ * Returns undefined if `name` itself isn't a valid bare name (e.g. has
+ * uppercase chars) and no explicit ref is set — the caller should treat
+ * this as an authoring error.
+ */
+export declare function resolveMetaobjectsPackage(manifest: PackageManifest): string | undefined;
+//# sourceMappingURL=package.d.ts.map

package/dist/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../src/package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsCxB;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;;OAKG;;IAGH,sCAAsC;;IAGtC;;;;;;;;;OASG;;IAGH;;;;OAIG;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAU/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAYvF"}

package/dist/package.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+// Per the v0.3 AI-first metadata loading strategy: a package.meta.json is the
+// boundary between metadata bundles. Three fields total — name, version,
+// extends. No exports list; no @private. The package's metadata tree IS its
+// public API. See docs/strategy/2026-05-12-v0.3-ai-first-metadata-loading.md
+// §4.3.
+/**
+ * Validates a package version string. npm-compatible: semver basics
+ * (major.minor.patch with optional prerelease/build). Not a full semver
+ * parser — strict-enough for now.
+ */
+const VersionStringSchema = z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/, "package version must follow semver (e.g. 1.2.0 or 1.2.0-alpha.1)");
+/**
+ * Validates a package extends entry. Either a bare package name or
+ * a name with a semver range — npm-style. Range parsing is shallow
+ * for v0.3 v0.1; full range resolution lands when multi-package
+ * loading actually ships.
+ */
+const ExtendsEntrySchema = z.string().min(1);
+/**
+ * Validates a canonical metaobjects package ref: snake_case segments
+ * separated by `::`. Examples: `trainer_website`, `acme::common::user_mgmt`.
+ * Used in metadata file refs (extends:, super:) cross-language.
+ */
+const MetaobjectsPackageSchema = z.string().regex(/^[a-z][a-z0-9_]*(::[a-z][a-z0-9_]*)*$/, "metaobjectsPackage must be snake_case segments separated by :: (e.g. acme::common::user_mgmt)");
+/**
+ * The package.meta.json schema. Authoring this is the one-time cost of
+ * defining a metadata package; subsequent edits should be rare.
+ */
+export const PackageManifestSchema = z.object({
+    /**
+     * Canonical name of the package in the language's native package manager.
+     * Conventionally `@scope/name` (npm-style) for TS, but bare names also
+     * work. Each language's package config (pom.xml, .csproj, pyproject.toml)
+     * uses its own native field for this — only TS uses `name` here.
+     */
+    name: z.string().min(1),
+    /** Semver version of this package. */
+    version: VersionStringSchema,
+    /**
+     * Optional cross-language canonical ref for this package, used inside
+     * metadata files (extends:, super:) and for cross-language consumption.
+     * If omitted, derived from `name` via a simple rule: `@scope/name` →
+     * `scope::name` (strip @, replace `/` with `::`). Hyphens stay as-is in
+     * the auto-derived form — for hierarchical naming users declare this
+     * field explicitly.
+     *
+     * Per v0.3 strategy doc §8.2.
+     */
+    metaobjectsPackage: MetaobjectsPackageSchema.optional(),
+    /**
+     * Other packages whose metadata trees this package extends. Each entry is
+     * a package name; the loader resolves it to the matching peer package.
+     * Empty/omitted means this package has no upstream dependencies.
+     */
+    extends: z.array(ExtendsEntrySchema).default([]),
+});
+export const PACKAGE_MANIFEST_FILE = "package.meta.json";
+/**
+ * Read a package.meta.json from a given .meta/ root, if present.
+ * Returns undefined when the file isn't there — packages are optional in
+ * v0.3 v0.1 (loadMemory still works for single-package usage without one,
+ * and forge init scaffolds one but doesn't enforce its presence).
+ */
+export async function readPackageManifest(metaDir) {
+    const path = join(metaDir, PACKAGE_MANIFEST_FILE);
+    try {
+        const s = await stat(path);
+        if (!s.isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const raw = await readFile(path, "utf8");
+    return PackageManifestSchema.parse(JSON.parse(raw));
+}
+/**
+ * Return the canonical metaobjects package ref for a manifest. Uses the
+ * explicit `metaobjectsPackage` field if set; otherwise derives from `name`
+ * via the simple rule: `@scope/foo-bar` → `scope::foo-bar` (strip @,
+ * replace `/` with `::`, leave hyphens). For hierarchical or non-trivial
+ * naming users declare `metaobjectsPackage` explicitly.
+ *
+ * Returns undefined if `name` itself isn't a valid bare name (e.g. has
+ * uppercase chars) and no explicit ref is set — the caller should treat
+ * this as an authoring error.
+ */
+export function resolveMetaobjectsPackage(manifest) {
+    if (manifest.metaobjectsPackage !== undefined)
+        return manifest.metaobjectsPackage;
+    // Auto-derive from name: strip leading @, replace / with ::, lowercase
+    // remains untouched — npm names are already lowercase per registry rules.
+    const stripped = manifest.name.replace(/^@/, "");
+    const derived = stripped.replace(/\//g, "::");
+    // Validate that the derived form is a legal canonical ref. If not,
+    // return undefined so the caller can surface a clear error.
+    if (!/^[a-z][a-z0-9_-]*(::[a-z][a-z0-9_-]*)*$/.test(derived)) {
+        return undefined;
+    }
+    return derived;
+}
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../src/package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,8EAA8E;AAC9E,yEAAyE;AACzE,4EAA4E;AAC5E,6EAA6E;AAC7E,QAAQ;AAER;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAC1C,sDAAsD,EACtD,kEAAkE,CACnE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;GAIG;AACH,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAC/C,uCAAuC,EACvC,+FAA+F,CAChG,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C;;;;;OAKG;IACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEvB,sCAAsC;IACtC,OAAO,EAAE,mBAAmB;IAE5B;;;;;;;;;OASG;IACH,kBAAkB,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAEvD;;;;OAIG;IACH,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACjD,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE;YAAE,OAAO,SAAS,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,OAAO,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAyB;IACjE,IAAI,QAAQ,CAAC,kBAAkB,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC,kBAAkB,CAAC;IAClF,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9C,mEAAmE;IACnE,4DAA4D;IAC5D,IAAI,CAAC,yCAAyC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,5 @@
+export declare function recordPath(metaRoot: string, type: string, id: string, opts?: {
+    pending?: boolean;
+}): string;
+export declare function resolveMetaRoot(startDir: string): Promise<string>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,MAAM,CAKR;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcvE"}

package/dist/paths.js

@@ -0,0 +1,26 @@
+import { stat } from "node:fs/promises";
+import { join, dirname, resolve, parse } from "node:path";
+export function recordPath(metaRoot, type, id, opts = {}) {
+    const segments = opts.pending
+        ? ["memory", "_pending", type, `${id}.json`]
+        : ["memory", type, `${id}.json`];
+    return join(metaRoot, ...segments);
+}
+export async function resolveMetaRoot(startDir) {
+    let current = resolve(startDir);
+    const root = parse(current).root;
+    while (current !== root) {
+        const candidate = join(current, ".meta");
+        try {
+            const s = await stat(candidate);
+            if (s.isDirectory())
+                return candidate;
+        }
+        catch {
+            // not present at this level
+        }
+        current = dirname(current);
+    }
+    throw new Error(`no .meta directory found walking up from ${startDir}`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,IAAY,EACZ,EAAU,EACV,OAA8B,EAAE;IAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO;QAC3B,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC;QAC5C,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,IAAI,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;IACjC,OAAO,OAAO,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC;YAChC,IAAI,CAAC,CAAC,WAAW,EAAE;gBAAE,OAAO,SAAS,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,4BAA4B;QAC9B,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,4CAA4C,QAAQ,EAAE,CAAC,CAAC;AAC1E,CAAC"}