@metaobjectsdev/sdk 0.5.0-rc.1

package/src/storage/errors.ts

@@ -0,0 +1,23 @@
+export class MetaForgeRecordNotFoundError extends Error {
+  constructor(public readonly path: string) {
+    super(`Record not found: ${path}`);
+    this.name = "MetaForgeRecordNotFoundError";
+  }
+}
+
+export class MetaForgeAlreadyPromotedError extends Error {
+  constructor(public readonly path: string) {
+    super(`A canonical record already exists at: ${path}`);
+    this.name = "MetaForgeAlreadyPromotedError";
+  }
+}
+
+export class MetaForgeRecordParseError extends Error {
+  constructor(
+    public readonly path: string,
+    public override readonly cause: unknown,
+  ) {
+    super(`Failed to parse record at ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = "MetaForgeRecordParseError";
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,10 @@
+export { readRecord, recordExists } from "./read.js";
+export { writeRecord, removeRecord } from "./write.js";
+export { listRecords } from "./list.js";
+export type { ListOptions } from "./list.js";
+export { promoteRecord, supersede } from "./lifecycle.js";
+export {
+  MetaForgeRecordNotFoundError,
+  MetaForgeAlreadyPromotedError,
+  MetaForgeRecordParseError,
+} from "./errors.js";

package/src/storage/lifecycle.ts

@@ -0,0 +1,38 @@
+import type { AnyRecord } from "../records/any.js";
+import type { RecordType } from "../records/core.js";
+import { readRecord, recordExists } from "./read.js";
+import { writeRecord, removeRecord } from "./write.js";
+import { MetaForgeAlreadyPromotedError, MetaForgeRecordNotFoundError } from "./errors.js";
+import { recordPath } from "../paths.js";
+
+export async function promoteRecord(
+  metaRoot: string,
+  type: RecordType,
+  id: string,
+): Promise<void> {
+  if (!(await recordExists(metaRoot, type, id, { pending: true }))) {
+    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, type, id, { pending: true }));
+  }
+  if (await recordExists(metaRoot, type, id)) {
+    throw new MetaForgeAlreadyPromotedError(recordPath(metaRoot, type, id));
+  }
+  const record = await readRecord(metaRoot, type, id, { pending: true });
+  await writeRecord(metaRoot, record);
+  await removeRecord(metaRoot, type, id, { pending: true });
+}
+
+export async function supersede(
+  metaRoot: string,
+  oldId: string,
+  newRecord: AnyRecord,
+): Promise<void> {
+  if (!(await recordExists(metaRoot, newRecord.type, oldId))) {
+    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, newRecord.type, oldId));
+  }
+  // Write the new record first, so a failure leaves the old record intact.
+  await writeRecord(metaRoot, newRecord);
+  // Then update the old record to mark it superseded.
+  const old = await readRecord(metaRoot, newRecord.type, oldId);
+  const updated = { ...old, superseded_by: newRecord.id };
+  await writeRecord(metaRoot, updated);
+}

package/src/storage/list.ts

@@ -0,0 +1,53 @@
+import { readdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import type { AnyRecord } from "../records/any.js";
+import type { RecordType } from "../records/core.js";
+import { recordPath } from "../paths.js";
+import { readRecord } from "./read.js";
+
+export interface ListOptions {
+  pending?: boolean;
+  onInvalid?: (path: string, err: unknown) => void;
+}
+
+export async function listRecords(
+  metaRoot: string,
+  type: RecordType,
+  opts: ListOptions = {},
+): Promise<AnyRecord[]> {
+  const dir = directoryFor(metaRoot, type, opts.pending);
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    if (isNoEntError(err)) return [];
+    throw err;
+  }
+  const results: AnyRecord[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const id = basename(entry, ".json");
+    try {
+      const rec = await readRecord(metaRoot, type, id, opts.pending ? { pending: true } : {});
+      results.push(rec);
+    } catch (err) {
+      opts.onInvalid?.(join(dir, entry), err);
+    }
+  }
+  return results;
+}
+
+function directoryFor(metaRoot: string, type: RecordType, pending?: boolean): string {
+  // Re-derive from a sentinel id so we use a single source of truth for layout.
+  const sentinelPath = recordPath(metaRoot, type, "__sentinel__", pending ? { pending: true } : {});
+  return sentinelPath.slice(0, sentinelPath.length - "__sentinel__.json".length - 1);
+}
+
+function isNoEntError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "code" in err &&
+    (err as { code: unknown }).code === "ENOENT"
+  );
+}

package/src/storage/read.ts

@@ -0,0 +1,54 @@
+import { readFile, stat } from "node:fs/promises";
+import type { AnyRecord } from "../records/any.js";
+import { AnyRecord as AnyRecordSchema } from "../records/any.js";
+import type { RecordType } from "../records/core.js";
+import { recordPath } from "../paths.js";
+import { MetaForgeRecordNotFoundError, MetaForgeRecordParseError } from "./errors.js";
+
+export async function readRecord(
+  metaRoot: string,
+  type: RecordType,
+  id: string,
+  opts: { pending?: boolean } = {},
+): Promise<AnyRecord> {
+  const path = recordPath(metaRoot, type, id, opts);
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if (isNoEntError(err)) throw new MetaForgeRecordNotFoundError(path);
+    throw err;
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch (err) {
+    throw new MetaForgeRecordParseError(path, err);
+  }
+  const result = AnyRecordSchema.safeParse(parsedJson);
+  if (!result.success) throw new MetaForgeRecordParseError(path, result.error);
+  return result.data;
+}
+
+export async function recordExists(
+  metaRoot: string,
+  type: RecordType,
+  id: string,
+  opts: { pending?: boolean } = {},
+): Promise<boolean> {
+  try {
+    await stat(recordPath(metaRoot, type, id, opts));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isNoEntError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "code" in err &&
+    (err as { code: unknown }).code === "ENOENT"
+  );
+}

package/src/storage/write.ts

@@ -0,0 +1,32 @@
+import { mkdir, writeFile, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { AnyRecord } from "../records/any.js";
+import { AnyRecord as AnyRecordSchema } from "../records/any.js";
+import { recordPath } from "../paths.js";
+import { MetaForgeRecordNotFoundError } from "./errors.js";
+import { recordExists } from "./read.js";
+
+export async function writeRecord(
+  metaRoot: string,
+  record: AnyRecord,
+  opts: { pending?: boolean } = {},
+): Promise<void> {
+  // Validate before any IO
+  AnyRecordSchema.parse(record);
+
+  const path = recordPath(metaRoot, record.type, record.id, opts);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(record, null, 2) + "\n", "utf8");
+}
+
+export async function removeRecord(
+  metaRoot: string,
+  type: AnyRecord["type"],
+  id: string,
+  opts: { pending?: boolean } = {},
+): Promise<void> {
+  if (!(await recordExists(metaRoot, type, id, opts))) {
+    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, type, id, opts));
+  }
+  await unlink(recordPath(metaRoot, type, id, opts));
+}

package/src/workspace.ts

@@ -0,0 +1,342 @@
+// Workspace discovery — finds peer metadata packages in a monorepo via the
+// workspace conventions used by pnpm/npm/bun. The result is a registry of
+// `package.meta.json` files keyed by their `name` and `metaobjectsPackage`,
+// used by loadMemory (when extends: is present) and by future cross-package
+// codegen/migrate flows.
+//
+// Discovery sources (first match wins, walking up from cwd):
+//   - pnpm-workspace.yaml      (packages: array)
+//   - package.json workspaces  (array of globs OR { packages: [...] })
+//
+// This is the prototype implementation. Full v0.3 SP2 will harden:
+//   - Bun workspaces (currently mirrors package.json field)
+//   - Cargo / Maven workspaces (future polyglot support)
+//   - Lockfile-style resolution + version range matching
+//   - Better error messages on circular extends, missing packages
+
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve, basename } from "node:path";
+import {
+  type PackageManifest,
+  PackageManifestSchema,
+  PACKAGE_MANIFEST_FILE,
+  resolveMetaobjectsPackage,
+} from "./package.js";
+
+const PNPM_WORKSPACE_FILE = "pnpm-workspace.yaml";
+const PACKAGE_JSON = "package.json";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface WorkspacePackage {
+  /** Absolute path to the .meta/ directory. */
+  metaDir: string;
+  /** The parsed package.meta.json. */
+  manifest: PackageManifest;
+  /** The canonical metaobjects ref (resolved via resolveMetaobjectsPackage). */
+  metaobjectsPackage: string;
+}
+
+export interface Workspace {
+  /** Absolute path to the workspace root (where pnpm-workspace.yaml or package.json lives). */
+  root: string;
+  /** All metadata packages found under workspace globs. */
+  packages: WorkspacePackage[];
+  /** Look up by package.meta.json `name` (e.g., "@acme/shared"). */
+  findByName(name: string): WorkspacePackage | undefined;
+  /** Look up by canonical metaobjects ref (e.g., "acme::shared"). */
+  findByMetaobjectsPackage(ref: string): WorkspacePackage | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace root discovery
+// ---------------------------------------------------------------------------
+
+interface WorkspaceConfig {
+  root: string;
+  /** Workspace globs (e.g., "packages/*"). */
+  globs: string[];
+}
+
+async function readPnpmWorkspaceFile(path: string): Promise<string[] | undefined> {
+  try {
+    const content = await readFile(path, "utf8");
+    return extractPnpmPackages(content);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extract the `packages:` glob list from pnpm-workspace.yaml. Tiny parser —
+ * sufficient for the simple-list format pnpm actually emits. Not a general
+ * YAML parser; doesn't support quoted strings with special chars, flow
+ * mappings, anchors, etc.
+ */
+export function extractPnpmPackages(yaml: string): string[] {
+  const lines = yaml.split(/\r?\n/);
+  const result: string[] = [];
+  let inPackages = false;
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/#.*$/, "").trimEnd();
+    if (line.length === 0) continue;
+    if (/^packages\s*:/.test(line)) {
+      inPackages = true;
+      continue;
+    }
+    if (inPackages) {
+      const match = /^\s+-\s+['"]?([^'"]+)['"]?\s*$/.exec(line);
+      if (match !== null) {
+        result.push(match[1]!);
+        continue;
+      }
+      // Non-list line at the same or lower indent ends the packages: block
+      if (/^[A-Za-z_]/.test(line)) {
+        inPackages = false;
+      }
+    }
+  }
+  return result;
+}
+
+async function readPackageJsonWorkspaces(path: string): Promise<string[] | undefined> {
+  try {
+    const content = await readFile(path, "utf8");
+    const parsed = JSON.parse(content) as {
+      workspaces?: string[] | { packages?: string[] };
+    };
+    if (Array.isArray(parsed.workspaces)) return parsed.workspaces;
+    if (parsed.workspaces && Array.isArray(parsed.workspaces.packages)) {
+      return parsed.workspaces.packages;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Walk up from `start` looking for the first directory with a workspace config. */
+async function findWorkspaceConfig(start: string): Promise<WorkspaceConfig | undefined> {
+  let dir = resolve(start);
+  // Cap walk-up at filesystem root; in practice we'll find or stop in a few steps.
+  while (true) {
+    const pnpmPath = join(dir, PNPM_WORKSPACE_FILE);
+    const pnpmGlobs = await readPnpmWorkspaceFile(pnpmPath);
+    if (pnpmGlobs !== undefined && pnpmGlobs.length > 0) {
+      return { root: dir, globs: pnpmGlobs };
+    }
+
+    const pkgPath = join(dir, PACKAGE_JSON);
+    const pkgGlobs = await readPackageJsonWorkspaces(pkgPath);
+    if (pkgGlobs !== undefined && pkgGlobs.length > 0) {
+      return { root: dir, globs: pkgGlobs };
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) return undefined; // hit filesystem root
+    dir = parent;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Glob expansion (simple, matches workspace-style patterns)
+// ---------------------------------------------------------------------------
+
+/** Expand a workspace glob like "packages/*" relative to root. Returns directory paths. */
+async function expandGlob(root: string, glob: string): Promise<string[]> {
+  // Strip trailing `/` for normalization
+  const pattern = glob.replace(/\/$/, "");
+
+  // No wildcard: literal directory
+  if (!pattern.includes("*")) {
+    const literal = join(root, pattern);
+    try {
+      const s = await stat(literal);
+      return s.isDirectory() ? [literal] : [];
+    } catch {
+      return [];
+    }
+  }
+
+  // Split into prefix segments (literal) + last segment with wildcard.
+  // Supports the common cases: "packages/*", "apps/*", "packages/foo-*".
+  // Doesn't support deep `**` globs in this prototype.
+  const segments = pattern.split("/");
+  const lastSegment = segments.pop()!;
+  const prefixDir = join(root, ...segments);
+
+  let entries: string[];
+  try {
+    entries = await readdir(prefixDir);
+  } catch {
+    return [];
+  }
+
+  const matcher = matchGlobSegment(lastSegment);
+  const result: string[] = [];
+  for (const entry of entries) {
+    if (!matcher(entry)) continue;
+    const full = join(prefixDir, entry);
+    try {
+      const s = await stat(full);
+      if (s.isDirectory()) result.push(full);
+    } catch {
+      // skip unreadable
+    }
+  }
+  return result;
+}
+
+function matchGlobSegment(pattern: string): (value: string) => boolean {
+  if (pattern === "*") return () => true;
+  const regex = new RegExp(
+    "^" +
+      pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*") +
+      "$",
+  );
+  return (value) => regex.test(value);
+}
+
+// ---------------------------------------------------------------------------
+// Public: discoverWorkspace
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover the metaobjects workspace containing `cwd`. Returns undefined if
+ * no workspace config (pnpm-workspace.yaml or package.json workspaces) is
+ * found walking up the directory tree, OR if no `.meta/package.meta.json`
+ * files are present in the workspace packages.
+ *
+ * The returned Workspace has every package's manifest pre-loaded; callers
+ * can look up peers by name or canonical metaobjects ref.
+ */
+export async function discoverWorkspace(cwd: string): Promise<Workspace | undefined> {
+  const config = await findWorkspaceConfig(cwd);
+  if (config === undefined) return undefined;
+
+  // Expand all workspace globs
+  const packageDirs: string[] = [];
+  for (const glob of config.globs) {
+    packageDirs.push(...(await expandGlob(config.root, glob)));
+  }
+
+  // Also include the workspace root itself if it has a .meta/ —
+  // common pattern for root-level "the app" metadata.
+  const rootMetaDir = join(config.root, ".meta");
+  try {
+    const s = await stat(rootMetaDir);
+    if (s.isDirectory()) packageDirs.push(config.root);
+  } catch {
+    // no root-level .meta — fine
+  }
+
+  // For each package dir, look for .meta/package.meta.json
+  const packages: WorkspacePackage[] = [];
+  const seenDirs = new Set<string>();
+  for (const pkgDir of packageDirs) {
+    if (seenDirs.has(pkgDir)) continue;
+    seenDirs.add(pkgDir);
+    const metaDir = join(pkgDir, ".meta");
+    try {
+      const s = await stat(metaDir);
+      if (!s.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const manifestPath = join(metaDir, PACKAGE_MANIFEST_FILE);
+    let raw: string;
+    try {
+      raw = await readFile(manifestPath, "utf8");
+    } catch {
+      continue; // no manifest = not a metadata package
+    }
+    const manifest = PackageManifestSchema.parse(JSON.parse(raw));
+    const canonical = resolveMetaobjectsPackage(manifest);
+    if (canonical === undefined) {
+      throw new Error(
+        `package.meta.json in ${metaDir} has a name "${manifest.name}" that cannot be auto-derived to a canonical ref; declare metaobjectsPackage explicitly`,
+      );
+    }
+    packages.push({ metaDir, manifest, metaobjectsPackage: canonical });
+  }
+
+  if (packages.length === 0) return undefined;
+
+  return {
+    root: config.root,
+    packages,
+    findByName(name: string) {
+      return packages.find((p) => p.manifest.name === name);
+    },
+    findByMetaobjectsPackage(ref: string) {
+      return packages.find((p) => p.metaobjectsPackage === ref);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Resolve extends graph
+// ---------------------------------------------------------------------------
+
+/**
+ * For a given package (specified by its .meta/ directory), walk its `extends:`
+ * deps transitively via the workspace and return the full ordered list of
+ * packages to load — dependencies first, the target package last.
+ *
+ * Throws on:
+ *   - Missing package referenced by extends:
+ *   - Cycles in the extends graph
+ */
+export function resolveExtendsOrder(
+  workspace: Workspace,
+  startMetaDir: string,
+): WorkspacePackage[] {
+  const startPkg = workspace.packages.find((p) => p.metaDir === startMetaDir);
+  if (startPkg === undefined) {
+    throw new Error(
+      `metadata package at ${startMetaDir} is not part of the discovered workspace (root: ${workspace.root})`,
+    );
+  }
+
+  const ordered: WorkspacePackage[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function visit(pkg: WorkspacePackage): void {
+    if (visited.has(pkg.metaobjectsPackage)) return;
+    if (visiting.has(pkg.metaobjectsPackage)) {
+      throw new Error(
+        `cycle in extends graph: ${[...visiting, pkg.metaobjectsPackage].join(" → ")}`,
+      );
+    }
+    visiting.add(pkg.metaobjectsPackage);
+    for (const dep of pkg.manifest.extends) {
+      const depPkg = workspace.findByName(dep) ?? workspace.findByMetaobjectsPackage(dep);
+      if (depPkg === undefined) {
+        throw new Error(
+          `package "${pkg.manifest.name}" extends "${dep}" but that package was not found in the workspace`,
+        );
+      }
+      visit(depPkg);
+    }
+    visiting.delete(pkg.metaobjectsPackage);
+    visited.add(pkg.metaobjectsPackage);
+    ordered.push(pkg);
+  }
+
+  visit(startPkg);
+  return ordered;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostic helpers
+// ---------------------------------------------------------------------------
+
+/** Human-readable label for a workspace package — useful for error messages. */
+export function packageLabel(pkg: WorkspacePackage): string {
+  return `${pkg.manifest.name} (${pkg.metaobjectsPackage}) at ${basename(dirname(pkg.metaDir))}`;
+}