@metamesh/cli 0.0.0-stage → 0.14.0

package/dist/authoring/check.d.ts

@@ -0,0 +1,4 @@
+import type { AuthoringFailure, CheckOptions, CheckSuccess } from "./types.js";
+/** Checks strict TypeScript and the selected entry-module contract without evaluating author source. */
+export declare function checkAuthoringSource(options: CheckOptions): Promise<CheckSuccess | AuthoringFailure>;
+//# sourceMappingURL=check.d.ts.map

package/dist/authoring/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/authoring/check.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAuB,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAgBpG,wGAAwG;AACxG,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,YAAY,GAAG,gBAAgB,CAAC,CA+G1C"}

package/dist/authoring/check.js

@@ -0,0 +1,118 @@
+import { access } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import ts from "typescript";
+import { AuthoringError, authoringFailure } from "./errors.js";
+function diagnostic(value) {
+    const location = value.file && value.start !== undefined
+        ? value.file.getLineAndCharacterOfPosition(value.start)
+        : undefined;
+    return {
+        code: `TS${value.code}`,
+        message: ts.flattenDiagnosticMessageText(value.messageText, "\n"),
+        severity: value.category === ts.DiagnosticCategory.Warning ? "warning" : "error",
+        ...(value.file === undefined ? {} : { file: value.file.fileName }),
+        ...(location === undefined ? {} : { line: location.line + 1, column: location.character + 1 }),
+    };
+}
+/** Checks strict TypeScript and the selected entry-module contract without evaluating author source. */
+export async function checkAuthoringSource(options) {
+    try {
+        if (options.kind !== "model" && options.kind !== "generator")
+            throw new AuthoringError("invocation", "INVALID_KIND", "Select --kind model or --kind generator.");
+        const entry = resolve(options.project ?? process.cwd(), options.entry);
+        await access(entry).catch(() => {
+            throw new AuthoringError("invocation", "ENTRY_NOT_FOUND", `Entry does not exist: ${entry}`);
+        });
+        const tsconfig = options.tsconfig === undefined
+            ? ts.findConfigFile(dirname(entry), (file) => ts.sys.fileExists(file))
+            : resolve(options.project ?? process.cwd(), options.tsconfig);
+        let parsed;
+        if (tsconfig !== undefined) {
+            const loaded = ts.readConfigFile(tsconfig, (file) => ts.sys.readFile(file));
+            if (loaded.error)
+                return {
+                    success: false,
+                    phase: "check",
+                    exitCode: 1,
+                    diagnostics: [diagnostic(loaded.error)],
+                };
+            parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, dirname(tsconfig));
+        }
+        const compilerOptions = {
+            target: ts.ScriptTarget.ES2023,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+            skipLibCheck: true,
+            ...parsed?.options,
+            strict: true,
+            noCheck: false,
+            noEmit: true,
+            noImplicitAny: true,
+            strictNullChecks: true,
+            strictFunctionTypes: true,
+            strictBindCallApply: true,
+            strictPropertyInitialization: true,
+            noImplicitThis: true,
+            useUnknownInCatchVariables: true,
+            alwaysStrict: true,
+            incremental: false,
+            composite: false,
+            declaration: false,
+            declarationMap: false,
+            emitDeclarationOnly: false,
+        };
+        const program = ts.createProgram({ rootNames: [entry], options: compilerOptions });
+        const source = program.getSourceFile(entry);
+        const diagnostics = [...(parsed?.errors ?? []), ...ts.getPreEmitDiagnostics(program)].map(diagnostic);
+        const checker = program.getTypeChecker();
+        const moduleSymbol = source === undefined ? undefined : checker.getSymbolAtLocation(source);
+        const exports = moduleSymbol === undefined ? [] : checker.getExportsOfModule(moduleSymbol);
+        if (!exports.some((symbol) => symbol.getName() === "default") ||
+            (options.kind === "generator" && !exports.some((symbol) => symbol.getName() === "definition")))
+            diagnostics.push({
+                code: "AUTHORING_EXPORTS",
+                message: options.kind === "generator"
+                    ? "Generator entry must named-export definition and default-export its Generator module."
+                    : "Model entry must default-export its ModelProgram.",
+                severity: "error",
+                file: entry,
+            });
+        const defaultSymbol = exports.find((symbol) => symbol.getName() === "default");
+        if (defaultSymbol !== undefined && source !== undefined) {
+            const exported = checker.getTypeOfSymbolAtLocation(defaultSymbol, source);
+            const property = (type, name) => {
+                const symbol = checker.getPropertyOfType(type, name);
+                return symbol === undefined ? undefined : checker.getTypeOfSymbolAtLocation(symbol, source);
+            };
+            const candidate = options.kind === "model" ? exported : property(exported, "generate");
+            const generator = candidate === undefined ? undefined : property(candidate, "generate");
+            const kind = candidate === undefined ? undefined : property(candidate, "kind");
+            if (candidate === undefined ||
+                generator === undefined ||
+                generator.getCallSignatures().length === 0 ||
+                kind === undefined ||
+                checker.typeToString(kind) !== '"metamesh-model"')
+                diagnostics.push({
+                    code: "AUTHORING_PROGRAM_TYPE",
+                    message: options.kind === "model"
+                        ? "Default export must have the ModelProgram type returned by generate()."
+                        : "Default export must be a Generator module whose generate property is a ModelProgram.",
+                    severity: "error",
+                    file: entry,
+                });
+        }
+        if (diagnostics.some(({ severity }) => severity === "error"))
+            return { success: false, phase: "check", exitCode: 1, diagnostics };
+        return {
+            success: true,
+            entry,
+            kind: options.kind,
+            ...(tsconfig === undefined ? {} : { tsconfig: resolve(tsconfig) }),
+            diagnostics,
+        };
+    }
+    catch (error) {
+        return authoringFailure(error, "check");
+    }
+}
+//# sourceMappingURL=check.js.map

package/dist/authoring/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/authoring/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D,SAAS,UAAU,CAAC,KAAoB;IACtC,MAAM,QAAQ,GACZ,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QACrC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,KAAK,CAAC,KAAK,CAAC;QACvD,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO;QACL,IAAI,EAAE,KAAK,KAAK,CAAC,IAAI,EAAE;QACvB,OAAO,EAAE,EAAE,CAAC,4BAA4B,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC;QACjE,QAAQ,EAAE,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;QAChF,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;KAC/F,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAqB;IAErB,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW;YAC1D,MAAM,IAAI,cAAc,CACtB,YAAY,EACZ,cAAc,EACd,0CAA0C,CAC3C,CAAC;QACJ,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC7B,MAAM,IAAI,cAAc,CAAC,YAAY,EAAE,iBAAiB,EAAE,yBAAyB,KAAK,EAAE,CAAC,CAAC;QAC9F,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GACZ,OAAO,CAAC,QAAQ,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YACtE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClE,IAAI,MAAwC,CAAC;QAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5E,IAAI,MAAM,CAAC,KAAK;gBACd,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,OAAO;oBACd,QAAQ,EAAE,CAAC;oBACX,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;iBACxC,CAAC;YACJ,MAAM,GAAG,EAAE,CAAC,0BAA0B,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,eAAe,GAAuB;YAC1C,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM;YAC9B,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM;YAC5B,gBAAgB,EAAE,EAAE,CAAC,oBAAoB,CAAC,OAAO;YACjD,YAAY,EAAE,IAAI;YAClB,GAAG,MAAM,EAAE,OAAO;YAClB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,IAAI;YACZ,aAAa,EAAE,IAAI;YACnB,gBAAgB,EAAE,IAAI;YACtB,mBAAmB,EAAE,IAAI;YACzB,mBAAmB,EAAE,IAAI;YACzB,4BAA4B,EAAE,IAAI;YAClC,cAAc,EAAE,IAAI;YACpB,0BAA0B,EAAE,IAAI;YAChC,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,KAAK;YAChB,WAAW,EAAE,KAAK;YAClB,cAAc,EAAE,KAAK;YACrB,mBAAmB,EAAE,KAAK;SAC3B,CAAC;QACF,MAAM,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC,CAAC;QACnF,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACvF,UAAU,CACX,CAAC;QACF,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC5F,MAAM,OAAO,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC;QAC3F,IACE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,SAAS,CAAC;YACzD,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,YAAY,CAAC,CAAC;YAE9F,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,mBAAmB;gBACzB,OAAO,EACL,OAAO,CAAC,IAAI,KAAK,WAAW;oBAC1B,CAAC,CAAC,uFAAuF;oBACzF,CAAC,CAAC,mDAAmD;gBACzD,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,KAAK;aACZ,CAAC,CAAC;QACL,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC;QAC/E,IAAI,aAAa,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,yBAAyB,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;YAC1E,MAAM,QAAQ,GAAG,CAAC,IAAa,EAAE,IAAY,EAAuB,EAAE;gBACpE,MAAM,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACrD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC9F,CAAC,CAAC;YACF,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACvF,MAAM,SAAS,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YACxF,MAAM,IAAI,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC/E,IACE,SAAS,KAAK,SAAS;gBACvB,SAAS,KAAK,SAAS;gBACvB,SAAS,CAAC,iBAAiB,EAAE,CAAC,MAAM,KAAK,CAAC;gBAC1C,IAAI,KAAK,SAAS;gBAClB,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,kBAAkB;gBAEjD,WAAW,CAAC,IAAI,CAAC;oBACf,IAAI,EAAE,wBAAwB;oBAC9B,OAAO,EACL,OAAO,CAAC,IAAI,KAAK,OAAO;wBACtB,CAAC,CAAC,wEAAwE;wBAC1E,CAAC,CAAC,sFAAsF;oBAC5F,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,KAAK;iBACZ,CAAC,CAAC;QACP,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,KAAK,OAAO,CAAC;YAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;QACtE,OAAO;YACL,OAAO,EAAE,IAAI;YACb,KAAK;YACL,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClE,WAAW;SACZ,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/authoring/environment.d.ts

@@ -0,0 +1,29 @@
+import { type AuthoringEnvironment, type DocumentationEntry } from "./types.js";
+export declare const authoringPackageNames: string[];
+/** @internal Resolve only local installation scopes; Node's global fallback paths are excluded. */
+export declare function projectPackageDirectory(project: string, specifier: string): string | undefined;
+export declare function resolveProjectExport(project: string, specifier: string): string;
+export declare function confinedFile(directory: string, path: string): Promise<string>;
+/**
+ * Discovers project-local Modeling, CLI, and optional SDK/Testkit documentation.
+ * Rejects missing required packages, stale manifests, and mixed exact package versions.
+ */
+export declare function discoverAuthoringEnvironment(project?: string): Promise<AuthoringEnvironment>;
+/** An installed documentation match carrying the exact package identity that owns it. */
+export interface DocumentationSearchResult extends DocumentationEntry {
+    readonly packageName: string;
+    readonly packageVersion: string;
+}
+/**
+ * Ranks installed topic and symbol metadata without loading every document's body.
+ * Returns up to limit matches, defaulting to 10; supported limits are 1 through 50.
+ */
+export declare function searchAuthoringDocumentation(query: string, options?: {
+    readonly project?: string;
+    readonly limit?: number;
+}): Promise<readonly DocumentationSearchResult[]>;
+/** Reads one exact-version installed Markdown topic by its discovered ID, without executing source. */
+export declare function showAuthoringDocumentation(id: string, project?: string): Promise<DocumentationSearchResult & {
+    readonly markdown: string;
+}>;
+//# sourceMappingURL=environment.d.ts.map

package/dist/authoring/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/authoring/environment.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAGxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,qBAAqB,UAKjC,CAAC;AAEF,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA4B9F;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY/E;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBnF;AAsCD;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,SAAgB,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAgE/B;AAED,yFAAyF;AACzF,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACnE,OAAO,CAAC,SAAS,yBAAyB,EAAE,CAAC,CA6C/C;AAED,uGAAuG;AACvG,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,yBAAyB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBpE"}

package/dist/authoring/environment.js

@@ -0,0 +1,182 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { AuthoringError, isRecord } from "./errors.js";
+import { AUTHORING_PROTOCOL_VERSION, } from "./types.js";
+export const authoringPackageNames = [
+    "@metamesh/modeling",
+    "@metamesh/generator-sdk",
+    "@metamesh/testkit",
+    "@metamesh/cli",
+];
+/** @internal Resolve only local installation scopes; Node's global fallback paths are excluded. */
+export function projectPackageDirectory(project, specifier) {
+    const packageName = specifier.startsWith("@")
+        ? specifier.split("/").slice(0, 2).join("/")
+        : specifier.split("/")[0];
+    let current = resolve(project);
+    let checkedSelf = false;
+    while (true) {
+        const ownManifest = resolve(current, "package.json");
+        if (!checkedSelf && existsSync(ownManifest)) {
+            checkedSelf = true;
+            try {
+                if (JSON.parse(readFileSync(ownManifest, "utf8")).name ===
+                    packageName) {
+                    return current;
+                }
+            }
+            catch {
+                /* The export resolver below reports invalid installed metadata. */
+            }
+        }
+        const installed = resolve(current, "node_modules", packageName);
+        if (existsSync(resolve(installed, "package.json")))
+            return installed;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+export function resolveProjectExport(project, specifier) {
+    try {
+        if (projectPackageDirectory(project, specifier) === undefined)
+            throw new Error("No project-local installation.");
+        return createRequire(resolve(project, "package.json")).resolve(specifier);
+    }
+    catch {
+        throw new AuthoringError("environment", "PACKAGE_NOT_INSTALLED", `Cannot resolve ${specifier} from ${resolve(project)}. Install the matching MetaMesh package in that project.`);
+    }
+}
+export async function confinedFile(directory, path) {
+    if (isAbsolute(path) ||
+        path.includes("\\") ||
+        path.split("/").some((part) => part === ".." || part === ""))
+        throw new AuthoringError("artifact", "INVALID_PATH", `Invalid relative artifact/document path: ${path}`);
+    const root = await realpath(directory);
+    const file = await realpath(resolve(root, path));
+    const delta = relative(root, file);
+    if (delta.startsWith("..") || isAbsolute(delta))
+        throw new AuthoringError("artifact", "INVALID_PATH", `Path escapes its captured directory: ${path}`);
+    return file;
+}
+function readManifest(value, name) {
+    if (!isRecord(value) ||
+        value.formatVersion !== 1 ||
+        value.packageName !== name ||
+        typeof value.packageVersion !== "string" ||
+        !Array.isArray(value.documents) ||
+        value.documents.length === 0 ||
+        value.documents.length > 10000)
+        throw new AuthoringError("environment", "INVALID_DOCUMENTATION", `Invalid installed documentation manifest for ${name}.`);
+    const ids = new Set();
+    for (const document of value.documents) {
+        if (!isRecord(document) ||
+            !["id", "title", "summary", "path", "importPath", "availability", "canonical"].every((key) => typeof document[key] === "string" && document[key].trim().length > 0) ||
+            !Array.isArray(document.keywords) ||
+            !document.keywords.every((keyword) => typeof keyword === "string") ||
+            ids.has(document.id))
+            throw new AuthoringError("environment", "INVALID_DOCUMENTATION", `Invalid or duplicate document in ${name}.`);
+        ids.add(document.id);
+    }
+    return value;
+}
+/**
+ * Discovers project-local Modeling, CLI, and optional SDK/Testkit documentation.
+ * Rejects missing required packages, stale manifests, and mixed exact package versions.
+ */
+export async function discoverAuthoringEnvironment(project = process.cwd()) {
+    const packages = [];
+    for (const name of authoringPackageNames) {
+        const installedDirectory = projectPackageDirectory(project, name);
+        if (installedDirectory === undefined &&
+            name !== "@metamesh/modeling" &&
+            name !== "@metamesh/cli")
+            continue;
+        const manifestPath = resolveProjectExport(project, `${name}/docs/manifest.json`);
+        if ((await stat(manifestPath)).size > 8 * 1024 * 1024)
+            throw new AuthoringError("environment", "INVALID_DOCUMENTATION", `Documentation index exceeds 8 MiB: ${name}.`);
+        const manifest = readManifest(JSON.parse(await readFile(manifestPath, "utf8")), name);
+        const installed = JSON.parse(await readFile(resolve(installedDirectory, "package.json"), "utf8"));
+        if (!isRecord(installed) ||
+            installed.name !== name ||
+            installed.version !== manifest.packageVersion)
+            throw new AuthoringError("environment", "STALE_DOCUMENTATION", `Documentation version does not match installed ${name}. Rebuild or reinstall the package.`);
+        packages.push({
+            name,
+            version: manifest.packageVersion,
+            manifestPath,
+            documentCount: manifest.documents.length,
+        });
+    }
+    const versions = new Set(packages.map(({ version }) => version));
+    if (versions.size > 1)
+        throw new AuthoringError("environment", "PACKAGE_VERSION_MISMATCH", "Installed MetaMesh packages must have matching exact versions.");
+    return {
+        authoringProtocolVersion: AUTHORING_PROTOCOL_VERSION,
+        project: resolve(project),
+        packages,
+        capabilities: [
+            "docs",
+            "semantic-check",
+            "model",
+            ...(packages.some(({ name }) => name === "@metamesh/generator-sdk")
+                ? ["generator", "offline-font-fixtures"]
+                : []),
+            "captured-artifacts",
+            "render",
+            "export-3mf",
+        ],
+    };
+}
+/**
+ * Ranks installed topic and symbol metadata without loading every document's body.
+ * Returns up to limit matches, defaulting to 10; supported limits are 1 through 50.
+ */
+export async function searchAuthoringDocumentation(query, options = {}) {
+    const limit = options.limit ?? 10;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+        throw new AuthoringError("invocation", "INVALID_LIMIT", "Documentation limit must be an integer from 1 to 50.");
+    const words = query.toLocaleLowerCase("en-US").match(/[\p{L}\p{N}_-]+/gu) ?? [];
+    if (words.length === 0)
+        throw new AuthoringError("invocation", "EMPTY_QUERY", "Enter a documentation search query.");
+    const environment = await discoverAuthoringEnvironment(options.project);
+    const indexed = await Promise.all(environment.packages.map(async (pkg) => ({
+        pkg,
+        manifest: readManifest(JSON.parse(await readFile(pkg.manifestPath, "utf8")), pkg.name),
+    })));
+    return indexed
+        .flatMap(({ pkg, manifest }) => manifest.documents.map((document) => {
+        const heading = `${document.title} ${document.id} ${document.importPath}`.toLocaleLowerCase("en-US");
+        const haystack = `${heading} ${document.summary} ${document.availability} ${document.keywords.join(" ")}`.toLocaleLowerCase("en-US");
+        const score = words.reduce((sum, word) => sum + (heading.includes(word) ? 5 : haystack.includes(word) ? 1 : 0), 0);
+        return {
+            score,
+            result: { ...document, packageName: pkg.name, packageVersion: pkg.version },
+        };
+    }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.result.id.localeCompare(b.result.id, "en"))
+        .slice(0, limit)
+        .map(({ result }) => result);
+}
+/** Reads one exact-version installed Markdown topic by its discovered ID, without executing source. */
+export async function showAuthoringDocumentation(id, project) {
+    const environment = await discoverAuthoringEnvironment(project);
+    for (const pkg of environment.packages) {
+        const manifest = readManifest(JSON.parse(await readFile(pkg.manifestPath, "utf8")), pkg.name);
+        const document = manifest.documents.find((entry) => entry.id === id);
+        if (!document)
+            continue;
+        const file = await confinedFile(dirname(pkg.manifestPath), document.path);
+        const markdown = await readFile(file, "utf8");
+        if (Buffer.byteLength(markdown) > 512 * 1024)
+            throw new AuthoringError("environment", "DOCUMENT_TOO_LARGE", "Requested document exceeds the 512 KiB retrieval bound.");
+        return { ...document, packageName: pkg.name, packageVersion: pkg.version, markdown };
+    }
+    throw new AuthoringError("invocation", "DOCUMENT_NOT_FOUND", `No installed documentation topic has id ${id}.`);
+}
+//# sourceMappingURL=environment.js.map

package/dist/authoring/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/authoring/environment.ts"],"names":[],"mappings":"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"}

package/dist/authoring/errors.d.ts

@@ -0,0 +1,13 @@
+import type { AuthoringDiagnostic, AuthoringFailure, AuthoringPhase } from "./types.js";
+/** A classified authoring exception retaining its workflow phase, stable code, and exit status. */
+export declare class AuthoringError extends Error {
+    readonly phase: AuthoringPhase;
+    readonly code: string;
+    readonly exitCode: 1 | 2;
+    readonly diagnostics?: readonly AuthoringDiagnostic[] | undefined;
+    constructor(phase: AuthoringPhase, code: string, message: string, exitCode?: 1 | 2, diagnostics?: readonly AuthoringDiagnostic[] | undefined);
+}
+/** Converts a thrown value to a failure envelope, preserving classified authoring diagnostics. */
+export declare function authoringFailure(error: unknown, fallbackPhase?: AuthoringPhase): AuthoringFailure;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/authoring/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/authoring/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExF,mGAAmG;AACnG,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,KAAK,EAAE,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,mBAAmB,EAAE;gBAJ5C,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,QAAQ,GAAE,CAAC,GAAG,CAAK,EACnB,WAAW,CAAC,EAAE,SAAS,mBAAmB,EAAE,YAAA;CAKxD;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,aAAa,GAAE,cAA8B,GAC5C,gBAAgB,CAsBlB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE"}

package/dist/authoring/errors.js

@@ -0,0 +1,43 @@
+/** A classified authoring exception retaining its workflow phase, stable code, and exit status. */
+export class AuthoringError extends Error {
+    phase;
+    code;
+    exitCode;
+    diagnostics;
+    constructor(phase, code, message, exitCode = 2, diagnostics) {
+        super(message);
+        this.phase = phase;
+        this.code = code;
+        this.exitCode = exitCode;
+        this.diagnostics = diagnostics;
+        this.name = "AuthoringError";
+    }
+}
+/** Converts a thrown value to a failure envelope, preserving classified authoring diagnostics. */
+export function authoringFailure(error, fallbackPhase = "environment") {
+    if (error instanceof AuthoringError)
+        return {
+            success: false,
+            phase: error.phase,
+            exitCode: error.exitCode,
+            diagnostics: error.diagnostics ?? [
+                { code: error.code, message: error.message, severity: "error" },
+            ],
+        };
+    return {
+        success: false,
+        phase: fallbackPhase,
+        exitCode: 2,
+        diagnostics: [
+            {
+                code: "TOOLING_ERROR",
+                message: error instanceof Error ? error.message : String(error),
+                severity: "error",
+            },
+        ],
+    };
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=errors.js.map

package/dist/authoring/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/authoring/errors.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IACA;IAEA;IACA;IALX,YACW,KAAqB,EACrB,IAAY,EACrB,OAAe,EACN,WAAkB,CAAC,EACnB,WAA4C;QAErD,KAAK,CAAC,OAAO,CAAC,CAAC;QANN,UAAK,GAAL,KAAK,CAAgB;QACrB,SAAI,GAAJ,IAAI,CAAQ;QAEZ,aAAQ,GAAR,QAAQ,CAAW;QACnB,gBAAW,GAAX,WAAW,CAAiC;QAGrD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,kGAAkG;AAClG,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,gBAAgC,aAAa;IAE7C,IAAI,KAAK,YAAY,cAAc;QACjC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI;gBAChC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;aAChE;SACF,CAAC;IACJ,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,aAAa;QACpB,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE;YACX;gBACE,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC/D,QAAQ,EAAE,OAAO;aAClB;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/authoring/render-client.d.ts

@@ -0,0 +1,6 @@
+import type { CaptureState, RenderView } from "./render-types.js";
+declare global {
+    var metameshCaptureState: CaptureState;
+    var metameshCaptureView: (view: RenderView) => void;
+}
+//# sourceMappingURL=render-client.d.ts.map

package/dist/authoring/render-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-client.d.ts","sourceRoot":"","sources":["../../src/authoring/render-client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,oBAAoB,EAAE,YAAY,CAAC;IACvC,IAAI,mBAAmB,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACrD"}

package/dist/authoring/render-client.js

@@ -0,0 +1,55 @@
+import { SRGBColorSpace, WebGLRenderer } from "three";
+import { createCaptureCamera, createCaptureScene } from "./render-scene.js";
+globalThis.metameshCaptureState = { status: "loading" };
+async function load() {
+    const response = await fetch("/scene.json");
+    if (!response.ok)
+        throw new Error("Could not load captured scene.");
+    const input = (await response.json());
+    const resources = await Promise.all(input.resources.map(async (resource) => {
+        const [positionsResponse, indicesResponse] = await Promise.all([
+            fetch(resource.positionsUrl),
+            fetch(resource.indicesUrl),
+        ]);
+        if (!positionsResponse.ok || !indicesResponse.ok)
+            throw new Error("Could not load captured buffers.");
+        return {
+            id: resource.id,
+            positions: new Float32Array(await positionsResponse.arrayBuffer()),
+            indices: new Uint32Array(await indicesResponse.arrayBuffer()),
+        };
+    }));
+    const capture = createCaptureScene(input, resources);
+    // Native Chromium PNG/WebP encoders round partially transparent MSAA edge colors
+    // differently. Crisp opaque coverage keeps both lossless artifacts pixel-equivalent.
+    const renderer = new WebGLRenderer({
+        antialias: false,
+        alpha: true,
+        preserveDrawingBuffer: true,
+    });
+    renderer.setPixelRatio(1);
+    renderer.setSize(input.width, input.height);
+    renderer.outputColorSpace = SRGBColorSpace;
+    if (input.background === "transparent")
+        renderer.setClearColor(0, 0);
+    document.body.append(renderer.domElement);
+    globalThis.metameshCaptureView = (view) => {
+        const { camera, record } = createCaptureCamera(capture.bounds, view, input.width, input.height);
+        renderer.render(capture.scene, camera);
+        // Flush the completed frame before exposing readiness to the screenshot owner.
+        renderer.getContext().finish();
+        globalThis.metameshCaptureState = { status: "ready", camera: record };
+    };
+    globalThis.addEventListener("pagehide", () => {
+        capture.dispose();
+        renderer.dispose();
+    }, { once: true });
+    globalThis.metameshCaptureView("isometric");
+}
+void load().catch((error) => {
+    globalThis.metameshCaptureState = {
+        status: "error",
+        message: error instanceof Error ? error.message : String(error),
+    };
+});
+//# sourceMappingURL=render-client.js.map

package/dist/authoring/render-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-client.js","sourceRoot":"","sources":["../../src/authoring/render-client.ts"],"names":[],"mappings":"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"}

package/dist/authoring/render-scene.d.ts

@@ -0,0 +1,22 @@
+import { Box3, Group, OrthographicCamera, Scene } from "three";
+import type { CaptureScene, RenderCamera, RenderView } from "./render-types.js";
+export interface RenderGeometry {
+    readonly id: string;
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+}
+interface CaptureSceneResources {
+    readonly scene: Scene;
+    readonly group: Group;
+    readonly bounds: Box3;
+    readonly dispose: () => void;
+}
+/** @internal Owns one capture's GPU-independent scene resources. */
+export declare function createCaptureScene(input: CaptureScene, resources: readonly RenderGeometry[]): CaptureSceneResources;
+/** @internal Fits every world-bounds corner in the selected orthographic view. */
+export declare function createCaptureCamera(bounds: Box3, view: RenderView, width: number, height: number): {
+    camera: OrthographicCamera;
+    record: RenderCamera;
+};
+export {};
+//# sourceMappingURL=render-scene.d.ts.map

package/dist/authoring/render-scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-scene.d.ts","sourceRoot":"","sources":["../../src/authoring/render-scene.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EAKJ,KAAK,EAIL,kBAAkB,EAClB,KAAK,EAEN,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,qBAAqB,CAoFvB;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,EACZ,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CA6CtD"}