@metaobjectsdev/sdk 0.9.0 → 0.10.0

package/src/agent-context/scaffold.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import type { AssembledFile, Stack } from "./types.js";
+
+/** Consumer-relative path of the sidecar manifest that tracks scaffolded files. */
+export const AGENT_CONTEXT_MANIFEST_PATH = ".metaobjects/.agent-context.json";
+
+export interface Manifest {
+  version: 1;
+  /**
+   * The MetaObjects version that last scaffolded this agent context. Used to nudge
+   * a re-scaffold when the installed version moves ahead (the skills/docs ship with
+   * the package, so an upgrade can leave the copied-in context stale). Optional for
+   * back-compat with manifests written before version tracking existed.
+   */
+  generatedBy?: string;
+  servers: string[];
+  clients: string[];
+  /** consumer-relative path → sha256 of the contents as last scaffolded. */
+  files: Record<string, string>;
+}
+
+export function hashContents(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+export interface ScaffoldDecision {
+  /** files to (over)write at their own path: new, or unmodified-since-last-scaffold. */
+  writes: { path: string; contents: string }[];
+  /** hand-edited files: write the fresh contents to `<path>.new`, leave the original. */
+  conflicts: { path: string; newPath: string; contents: string }[];
+  /** the manifest to persist after writing. */
+  manifest: Manifest;
+  /** paths the prior manifest tracked that are no longer assembled (e.g. stack shrank) — reported, never auto-deleted. */
+  removed: string[];
+}
+
+/**
+ * Decide what to write for a (re-)scaffold. Pure: filesystem access is via the
+ * `readCurrent` callback (returns the on-disk contents, or undefined if absent).
+ * A file is safe to overwrite iff it is absent, or its on-disk hash still equals
+ * the hash the prior manifest recorded (i.e. the user hasn't hand-edited it).
+ */
+export function planScaffold(opts: {
+  stack: Stack;
+  assembled: AssembledFile[];
+  prior: Manifest | undefined;
+  readCurrent: (path: string) => string | undefined;
+  /** The MetaObjects version doing the scaffold — stamped into the manifest. */
+  generatedBy: string;
+}): ScaffoldDecision {
+  const { stack, assembled, prior, readCurrent, generatedBy } = opts;
+  const writes: ScaffoldDecision["writes"] = [];
+  const conflicts: ScaffoldDecision["conflicts"] = [];
+  const files: Record<string, string> = {};
+
+  for (const f of assembled) {
+    files[f.path] = hashContents(f.contents);
+    const current = readCurrent(f.path);
+    if (current === undefined) {
+      writes.push({ path: f.path, contents: f.contents });
+      continue;
+    }
+    const priorHash = prior?.files[f.path];
+    if (priorHash !== undefined && hashContents(current) === priorHash) {
+      writes.push({ path: f.path, contents: f.contents }); // unmodified → refresh to latest
+    } else {
+      conflicts.push({ path: f.path, newPath: `${f.path}.new`, contents: f.contents });
+    }
+  }
+
+  const assembledPaths = new Set(assembled.map((f) => f.path));
+  const removed = prior ? Object.keys(prior.files).filter((p) => !assembledPaths.has(p)) : [];
+
+  return {
+    writes,
+    conflicts,
+    manifest: { version: 1, generatedBy, servers: stack.servers, clients: stack.clients, files },
+    removed,
+  };
+}
+
+/**
+ * A one-line nudge if the scaffolded agent context predates the installed MetaObjects
+ * (so `gen`/`verify` can remind the user to refresh the skills after an upgrade), or
+ * `null` when there is nothing to say — no agent context scaffolded, or it is in sync.
+ * Advisory only: never throws, never blocks, never writes.
+ */
+export function agentContextStaleness(opts: {
+  manifest: Manifest | undefined;
+  currentVersion: string;
+}): string | null {
+  const { manifest, currentVersion } = opts;
+  if (manifest === undefined) return null; // no agent context here → nothing to nudge
+  // Exact-equality on purpose: ANY drift nudges (a re-scaffold is cheap + idempotent).
+  // Don't "fix" this into a semver compare — a prerelease/build-metadata difference is
+  // still a reason to refresh, and the nudge is advisory, never a gate.
+  if (manifest.generatedBy === currentVersion) return null; // in sync
+  const from = manifest.generatedBy ?? "an older MetaObjects";
+  return (
+    `MetaObjects agent context was generated by ${from}; you're on ${currentVersion}. ` +
+    `Re-run 'meta init --docs-only --refresh-docs' to refresh the .claude/skills docs.`
+  );
+}

package/src/agent-context/types.ts

@@ -0,0 +1,31 @@
+export const SERVER_LANGS = ["typescript", "java", "kotlin", "csharp", "python"] as const;
+export type ServerLang = (typeof SERVER_LANGS)[number];
+
+export const CLIENT_FRAMEWORKS = ["react", "tanstack", "angular"] as const;
+export type ClientFramework = (typeof CLIENT_FRAMEWORKS)[number];
+
+/** Always-present token: schema migrations are TS-owned for every port (ADR-0015). */
+export const MIGRATION_TOKEN = "migration";
+
+export const SKILL_NAMES = [
+  "metaobjects-authoring",
+  "metaobjects-codegen",
+  "metaobjects-runtime-ui",
+  "metaobjects-prompts",
+  "metaobjects-verify",
+] as const;
+export type SkillName = (typeof SKILL_NAMES)[number];
+
+/** The resolved tech-stack of a consumer project. */
+export interface Stack {
+  servers: ServerLang[]; // deduped, in SERVER_LANGS order
+  clients: ClientFramework[]; // deduped, in CLIENT_FRAMEWORKS order
+  /** servers ∪ clients ∪ {"migration"} — the install-selection set for reference fragments. */
+  tokens: ReadonlySet<string>;
+}
+
+/** A file the assembler emits, path relative to the consumer project root. */
+export interface AssembledFile {
+  path: string; // e.g. ".metaobjects/AGENTS.md", ".claude/skills/metaobjects-codegen/references/java.md"
+  contents: string;
+}

package/src/agent-docs/body.ts

@@ -1,4 +1,8 @@
 // Agent reference docs body. Scaffolded into .metaobjects/AGENTS.md and CLAUDE.md by `meta init`.
+/**
+ * @deprecated The single-blob agent doc is replaced by the assembled agent-context
+ * (see `@metaobjectsdev/sdk/agent-context`). Kept only for back-compat; not scaffolded by `meta init`.
+ */
 export const AGENT_DOCS_BODY = `# Meta Forge — agent reference
 
 This file is scaffolded by \`meta init\` and lives alongside your \`metaobjects/\` records. It teaches AI coding assistants (Claude Code, Codex, etc.) how to read and modify MetaObjects metadata correctly. Refresh after CLI updates with \`meta init --refresh-docs\`.
@@ -148,7 +152,7 @@ The v0.2 keys (\`super\`, \`overlay\`, \`override\`, \`isInterface\`, \`implemen
 ### Package paths and inheritance
 
 - Package segments separated by \`::\` — \`acme::common::id\`
-- Relative references in \`extends:\` — \`..::common::id\` means "go up to parent package, descend into \`common::id\`"
+- Relative references in \`extends:\` — \`..::common::id\` means "go up to parent package, descend into \`common::id\`". Relative forms (\`..::\` parent-relative, leading \`::\` root-absolute) are a **YAML-authoring affordance only**; canonical JSON must be fully-qualified (a relative ref in JSON is rejected with \`ERR_RELATIVE_REF_IN_CANONICAL\`).
 - Cross-file resolution works as long as all files are passed to Loader (or live in the same \`metaobjects/\` directory)
 
 ### Two special intercepted attrs (parser-routed)
@@ -318,7 +322,7 @@ When a list needs computed columns (counts, sums, joined fields), create a **pro
         { "origin": { "subType": "aggregate",
             "@agg": "count", "@of": "Week.id", "@via": "Program.weeks" }}
       ]}},
-      { "identity": { "subType": "primary", "@fields": "id" } }
+      { "identity": { "subType": "primary", "name": "id", "@fields": "id" } }
     ]
   }
 }
@@ -517,7 +521,7 @@ metaobjects.config.ts         generator wiring (committed)
           "@forgeSource": "human",
           "@forgePrimaryLocation": "src/db/users.schema.ts",
           "children": [
-            {"field": {"name": "id", "extends": "..::common::id"}},
+            {"field": {"name": "id", "extends": "common::id"}},
             {"field": {"name": "email", "subType": "string",
               "@column": "email_address",
               "children": [{"validator": {"subType": "required"}}]

package/src/forge-types.ts

@@ -114,7 +114,7 @@ import {
 } from "@metaobjectsdev/metadata";
 
 /** Minimal concrete MetaData subclass used for all forge descriptive nodes. */
-class MetaForgeNode extends MetaData {}
+class ForgeNode extends MetaData {}
 
 function wildcardOf(childType: string): ChildRule {
   return {
@@ -133,7 +133,7 @@ function def(
   return {
     typeId: new TypeId(type, subType),
     description,
-    factory: (typeId, name) => new MetaForgeNode(typeId, name),
+    factory: (typeId, name) => new ForgeNode(typeId, name),
     childRules,
     attributes: [],
   };

package/src/index.ts

@@ -16,9 +16,9 @@ export {
   listRecords,
   promoteRecord,
   supersede,
-  MetaForgeRecordNotFoundError,
-  MetaForgeAlreadyPromotedError,
-  MetaForgeRecordParseError,
+  ForgeRecordNotFoundError,
+  ForgeAlreadyPromotedError,
+  ForgeRecordParseError,
 } from "./storage/index.js";
 export type { ListOptions } from "./storage/index.js";
 
@@ -103,3 +103,6 @@ export {
   PACKAGE_MANIFEST_FILE,
 } from "./package.js";
 export type { PackageManifest } from "./package.js";
+
+// Agent context — stack resolver, file assembler, and vocabulary types
+export * from "./agent-context/index.js";

package/src/memory.ts

@@ -97,7 +97,9 @@ export async function loadMemory(
   // against the merged tree afterwards) — dep packages first, current last.
   const paths = await collectMetadataPaths(repoRoot);
 
-  const loader = new MetaDataLoader({ registry });
+  const loader = new MetaDataLoader({
+    registry,
+  });
   const result = await loader.load(paths.map((p) => new FileSource(p)));
 
   if (result.errors.length > 0) {

package/src/storage/errors.ts

@@ -1,23 +1,23 @@
-export class MetaForgeRecordNotFoundError extends Error {
+export class ForgeRecordNotFoundError extends Error {
   constructor(public readonly path: string) {
     super(`Record not found: ${path}`);
-    this.name = "MetaForgeRecordNotFoundError";
+    this.name = "ForgeRecordNotFoundError";
   }
 }
 
-export class MetaForgeAlreadyPromotedError extends Error {
+export class ForgeAlreadyPromotedError extends Error {
   constructor(public readonly path: string) {
     super(`A canonical record already exists at: ${path}`);
-    this.name = "MetaForgeAlreadyPromotedError";
+    this.name = "ForgeAlreadyPromotedError";
   }
 }
 
-export class MetaForgeRecordParseError extends Error {
+export class ForgeRecordParseError 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";
+    this.name = "ForgeRecordParseError";
   }
 }

package/src/storage/index.ts

@@ -4,7 +4,7 @@ export { listRecords } from "./list.js";
 export type { ListOptions } from "./list.js";
 export { promoteRecord, supersede } from "./lifecycle.js";
 export {
-  MetaForgeRecordNotFoundError,
-  MetaForgeAlreadyPromotedError,
-  MetaForgeRecordParseError,
+  ForgeRecordNotFoundError,
+  ForgeAlreadyPromotedError,
+  ForgeRecordParseError,
 } from "./errors.js";

package/src/storage/lifecycle.ts

@@ -2,7 +2,7 @@ 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 { ForgeAlreadyPromotedError, ForgeRecordNotFoundError } from "./errors.js";
 import { recordPath } from "../paths.js";
 
 export async function promoteRecord(
@@ -11,10 +11,10 @@ export async function promoteRecord(
   id: string,
 ): Promise<void> {
   if (!(await recordExists(metaRoot, type, id, { pending: true }))) {
-    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, type, id, { pending: true }));
+    throw new ForgeRecordNotFoundError(recordPath(metaRoot, type, id, { pending: true }));
   }
   if (await recordExists(metaRoot, type, id)) {
-    throw new MetaForgeAlreadyPromotedError(recordPath(metaRoot, type, id));
+    throw new ForgeAlreadyPromotedError(recordPath(metaRoot, type, id));
   }
   const record = await readRecord(metaRoot, type, id, { pending: true });
   await writeRecord(metaRoot, record);
@@ -27,7 +27,7 @@ export async function supersede(
   newRecord: AnyRecord,
 ): Promise<void> {
   if (!(await recordExists(metaRoot, newRecord.type, oldId))) {
-    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, newRecord.type, oldId));
+    throw new ForgeRecordNotFoundError(recordPath(metaRoot, newRecord.type, oldId));
   }
   // Write the new record first, so a failure leaves the old record intact.
   await writeRecord(metaRoot, newRecord);

package/src/storage/read.ts

@@ -3,7 +3,7 @@ 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";
+import { ForgeRecordNotFoundError, ForgeRecordParseError } from "./errors.js";
 
 export async function readRecord(
   metaRoot: string,
@@ -16,17 +16,17 @@ export async function readRecord(
   try {
     raw = await readFile(path, "utf8");
   } catch (err) {
-    if (isNoEntError(err)) throw new MetaForgeRecordNotFoundError(path);
+    if (isNoEntError(err)) throw new ForgeRecordNotFoundError(path);
     throw err;
   }
   let parsedJson: unknown;
   try {
     parsedJson = JSON.parse(raw);
   } catch (err) {
-    throw new MetaForgeRecordParseError(path, err);
+    throw new ForgeRecordParseError(path, err);
   }
   const result = AnyRecordSchema.safeParse(parsedJson);
-  if (!result.success) throw new MetaForgeRecordParseError(path, result.error);
+  if (!result.success) throw new ForgeRecordParseError(path, result.error);
   return result.data;
 }
 

package/src/storage/write.ts

@@ -3,7 +3,7 @@ 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 { ForgeRecordNotFoundError } from "./errors.js";
 import { recordExists } from "./read.js";
 
 export async function writeRecord(
@@ -26,7 +26,7 @@ export async function removeRecord(
   opts: { pending?: boolean } = {},
 ): Promise<void> {
   if (!(await recordExists(metaRoot, type, id, opts))) {
-    throw new MetaForgeRecordNotFoundError(recordPath(metaRoot, type, id, opts));
+    throw new ForgeRecordNotFoundError(recordPath(metaRoot, type, id, opts));
   }
   await unlink(recordPath(metaRoot, type, id, opts));
 }