@metamesh/cli 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @metamesh/cli
 
+## 0.17.0
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies [d0cc194]
+- Updated dependencies
+- Updated dependencies
+  - @metamesh/modeling@0.17.0
+  - @metamesh/generator-sdk@0.17.0
+  - @metamesh/testkit@0.17.0
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/docs/guides/agent-authoring.md

@@ -123,12 +123,9 @@ A Generator entry named-exports `definition` and default-exports its module enve
 
 
 ```ts
-import {
-  defineGenerator,
-  defineGeneratorModule,
-  type GeneratorParams,
-} from "@metamesh/generator-sdk";
-import { box, generate } from "@metamesh/modeling";
+import { defineGenerator } from "@metamesh/generator-sdk";
+import { defineGeneratorModel } from "@metamesh/generator-sdk/modeling";
+import { box } from "@metamesh/modeling";
 
 export const definition = defineGenerator({
   id: "plate",
@@ -138,15 +135,17 @@ export const definition = defineGenerator({
   parameters: [{ id: "width", label: "Width", type: "number", default: 30, min: 1 }],
 });
 
-const model = generate<GeneratorParams<typeof definition>>(({ params, part }) =>
+export default defineGeneratorModel(definition, ({ params, part }) =>
   part("plate", box({ size: [params.width, 20, 6] }))
 );
-
-export default defineGeneratorModule({ definition, generate: model });
 ```
 
 
 
+`defineGeneratorModel` from the optional SDK `/modeling` adapter infers controls, prepared services,
+and assertion parameter IDs. It declares the ordinary Modeling program and package identity;
+the host still owns normalization, asset preparation, execution, and cleanup.
+
 ```bash
 pnpm exec metamesh check generator.ts --kind generator
 pnpm exec metamesh run generator.ts --kind generator --params values.json
@@ -197,12 +196,15 @@ pnpm add -D @metamesh/testkit
 ```
 
 Use `createGeneratorTestRunner(definition, runtime)` for a Generator's persistent generation
-session. Its `execute` method returns a discriminated result: handle `type: "invalid"` before
-reading a generated `model`. Dispose each successful `model` when finished and dispose the runner
-separately; snapshots remain usable after the runner is disposed.
-Unexpected execution or malformed-output errors reject instead of returning an `invalid` result.
-For an ordinary `ModelProgram`, use an [engine session](https://metamesh.studio/docs/engine/hosting) and the same assertions
-against its completed snapshot.
+session. `runner.withModel(parameters, callback)` awaits assertions and disposes its snapshot in
+`finally`; invalid output throws structured `GenerationError` diagnostics. Dispose the runner
+separately to release its session and caches. Testkit's `withModel(program, parameters, callback)`
+does the same for an ordinary `ModelProgram` and also disposes its temporary session; its optional
+fourth argument accepts session policy, prepared services, and a test-owned engine.
+
+Use `runner.execute` when a test needs explicit snapshot ownership or the discriminated invalid
+result. Handle `type: "invalid"` before reading a generated `model`, and dispose each successful
+snapshot separately. Unexpected execution or malformed-output errors reject in either path.
 
 The runner normalizes saved values. To probe deliberately invalid typed inputs without that
 recovery, call `runner.validate(parameters, { normalize: false })`. Validation checks declarations

package/dist/docs/manifest.json

@@ -1,7 +1,7 @@
 {
   "formatVersion": 1,
   "packageName": "@metamesh/cli",
-  "packageVersion": "0.16.0",
+  "packageVersion": "0.17.0",
   "documents": [
     {
       "id": "cli/guide/agent-authoring",

package/dist/docs/reference/authoring/AUTHORING_PROTOCOL_VERSION.md

@@ -2,7 +2,7 @@
 
 Version of the CLI authoring protocol, independent of package SemVer and engine compatibility.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 AUTHORING_PROTOCOL_VERSION = 1

package/dist/docs/reference/authoring/AuthoringDiagnostic.md

@@ -2,7 +2,7 @@
 
 A structured issue with optional source location, parameter association, and geometry context.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A structured issue with optional source location, parameter association, and geometry context. */

package/dist/docs/reference/authoring/AuthoringEnvironment.md

@@ -2,7 +2,7 @@
 
 The selected project's supported protocol, matching package releases, and available workflows.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** The selected project's supported protocol, matching package releases, and available workflows. */

package/dist/docs/reference/authoring/AuthoringError.md

@@ -2,7 +2,7 @@
 
 A classified authoring exception retaining its workflow phase, stable code, and exit status.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A classified authoring exception retaining its workflow phase, stable code, and exit status. */

package/dist/docs/reference/authoring/AuthoringFailure-type.md

@@ -2,7 +2,7 @@
 
 An unsuccessful command outcome; a failure directory does not establish a complete capture.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** An unsuccessful command outcome; a failure directory does not establish a complete capture. */

package/dist/docs/reference/authoring/AuthoringKind.md

@@ -2,7 +2,7 @@
 
 Selects a standalone ModelProgram entry or an SDK Generator module with a definition.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Selects a standalone ModelProgram entry or an SDK Generator module with a definition. */

package/dist/docs/reference/authoring/AuthoringPhase.md

@@ -2,7 +2,7 @@
 
 The workflow stage that rejected an invocation, source, asset, or captured artifact.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** The workflow stage that rejected an invocation, source, asset, or captured artifact. */

package/dist/docs/reference/authoring/CapturedBuffer.md

@@ -2,7 +2,7 @@
 
 A captured file's relative path, byte length, and SHA-256 integrity digest.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A captured file's relative path, byte length, and SHA-256 integrity digest. */

package/dist/docs/reference/authoring/CapturedGeometry.md

@@ -2,7 +2,7 @@
 
 Validated local-space mesh buffers loaded from a completed captured resource.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Validated local-space mesh buffers loaded from a completed captured resource. */

package/dist/docs/reference/authoring/CapturedPart.md

@@ -2,7 +2,7 @@
 
 Semantic part identity and appearance referencing a shared mesh with separate placement.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Semantic part identity and appearance referencing a shared mesh with separate placement. */

package/dist/docs/reference/authoring/CapturedResource.md

@@ -2,7 +2,7 @@
 
 A shared local-space mesh resource and its measurements, before per-part placement.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A shared local-space mesh resource and its measurements, before per-part placement. */

package/dist/docs/reference/authoring/CapturedRun.md

@@ -2,7 +2,7 @@
 
 A validated successful capture with its manifest and shared local geometry buffers.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A validated successful capture with its manifest and shared local geometry buffers. */

package/dist/docs/reference/authoring/CapturedRunManifest.md

@@ -2,7 +2,7 @@
 
 A completed attempt's provenance, effective inputs, diagnostics, and captured geometry.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A completed attempt's provenance, effective inputs, diagnostics, and captured geometry. */

package/dist/docs/reference/authoring/CheckOptions.md

@@ -2,7 +2,7 @@
 
 Source entry contract and project-local resolution settings for semantic checking.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Source entry contract and project-local resolution settings for semantic checking. */

package/dist/docs/reference/authoring/CheckSuccess.md

@@ -2,7 +2,7 @@
 
 A successful semantic check; source has not been evaluated and no geometry is captured.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A successful semantic check; source has not been evaluated and no geometry is captured. */

package/dist/docs/reference/authoring/DocumentationEntry.md

@@ -2,7 +2,7 @@
 
 Metadata for one installed Markdown guide or public API symbol.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Metadata for one installed Markdown guide or public API symbol. */

package/dist/docs/reference/authoring/DocumentationManifest.md

@@ -2,7 +2,7 @@
 
 Exact-package-version index exposed through the package's docs/manifest.json export.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Exact-package-version index exposed through the package's docs/manifest.json export. */

package/dist/docs/reference/authoring/DocumentationSearchResult.md

@@ -2,7 +2,7 @@
 
 An installed documentation match carrying the exact package identity that owns it.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** An installed documentation match carrying the exact package identity that owns it. */

package/dist/docs/reference/authoring/InstalledAuthoringPackage.md

@@ -2,7 +2,7 @@
 
 A project-local MetaMesh package and its verified documentation index.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A project-local MetaMesh package and its verified documentation index. */

package/dist/docs/reference/authoring/RenderCamera.md

@@ -2,7 +2,7 @@
 
 Recorded orthographic camera, expressed in millimetres and world coordinates.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Recorded orthographic camera, expressed in millimetres and world coordinates. */

package/dist/docs/reference/authoring/RenderFormat.md

@@ -2,7 +2,7 @@
 
 Image encodings; WebP is always lossless.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Image encodings; WebP is always lossless. */

package/dist/docs/reference/authoring/RenderOptions.md

@@ -2,7 +2,7 @@
 
 Options for rendering a previously captured model, without executing author code.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Options for rendering a previously captured model, without executing author code. */

package/dist/docs/reference/authoring/RenderResult.md

@@ -2,7 +2,7 @@
 
 Images always belong to one captured run and one unique output directory.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Images always belong to one captured run and one unique output directory. */

package/dist/docs/reference/authoring/RenderView.md

@@ -2,7 +2,7 @@
 
 Standard orthographic views in MetaMesh's Z-up coordinate system.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Standard orthographic views in MetaMesh's Z-up coordinate system. */

package/dist/docs/reference/authoring/RenderedImage.md

@@ -2,7 +2,7 @@
 
 A view and its provenance, also written beside the image as JSON.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A view and its provenance, also written beside the image as JSON. */

package/dist/docs/reference/authoring/RunOptions.md

@@ -2,7 +2,7 @@
 
 Inputs and bounded execution policy for one checked, trusted local source attempt.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Inputs and bounded execution policy for one checked, trusted local source attempt. */

package/dist/docs/reference/authoring/RunSuccess.md

@@ -2,7 +2,7 @@
 
 A successful checked execution; use this exact directory for subsequent inspection and rendering.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** A successful checked execution; use this exact directory for subsequent inspection and rendering. */

package/dist/docs/reference/authoring/authoringFailure-value.md

@@ -2,7 +2,7 @@
 
 Converts a thrown value to a failure envelope, preserving classified authoring diagnostics.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Converts a thrown value to a failure envelope, preserving classified authoring diagnostics. */

package/dist/docs/reference/authoring/checkAuthoringSource.md

@@ -2,7 +2,7 @@
 
 Checks strict TypeScript and the selected entry-module contract without evaluating author source.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Checks strict TypeScript and the selected entry-module contract without evaluating author source. */

package/dist/docs/reference/authoring/discoverAuthoringEnvironment.md

@@ -2,7 +2,7 @@
 
 Discovers project-local Modeling, CLI, and optional SDK/Testkit documentation. Rejects missing required packages, stale manifests, and mixed exact package versions.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /**

package/dist/docs/reference/authoring/inspectCapturedRun.md

@@ -2,7 +2,7 @@
 
 Validates a completed capture and returns its manifest with an optional semantic part selection. Original source is never evaluated; incomplete captures and unknown part IDs reject.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /**

package/dist/docs/reference/authoring/installAuthoringBrowser.md

@@ -2,7 +2,7 @@
 
 Explicit installation of this package's pinned Chromium. Never called by render.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Explicit installation of this package's pinned Chromium. Never called by render. */

package/dist/docs/reference/authoring/readCapturedRun.md

@@ -2,7 +2,7 @@
 
 Reads only immutable captured files. It never imports or executes original author source.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Reads only immutable captured files. It never imports or executes original author source. */

package/dist/docs/reference/authoring/renderCapturedRun.md

@@ -2,7 +2,7 @@
 
 Render validated persisted local geometry and placements. Source code is never imported, and a fresh capture directory prevents overlapping calls from overwriting evidence.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /**

package/dist/docs/reference/authoring/runAuthoringSource.md

@@ -2,7 +2,7 @@
 
 Checks and executes trusted local source in a disposable child, then captures its finalized geometry. Returns a success or failure envelope for this fresh attempt; failed attempts cannot be rendered.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /**

package/dist/docs/reference/authoring/searchAuthoringDocumentation.md

@@ -2,7 +2,7 @@
 
 Ranks distinct intent tokens in installed titles, keywords, and summaries without loading bodies. Exact symbol/topic/import lookup takes priority; equally complete matches favor guides. Returns up to limit matches, defaulting to 10; supported limits are 1 through 50.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /**

package/dist/docs/reference/authoring/showAuthoringDocumentation.md

@@ -2,7 +2,7 @@
 
 Reads one exact-version installed Markdown topic by its discovered ID, without executing source.
 
-Import from `@metamesh/cli/authoring` (@metamesh/cli@0.16.0).
+Import from `@metamesh/cli/authoring` (@metamesh/cli@0.17.0).
 
 ```ts
 /** Reads one exact-version installed Markdown topic by its discovered ID, without executing source. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metamesh/cli",
   "description": "Local MetaMesh authoring CLI and reusable Node tools for checking, captured generation, inspection, and rendering.",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
     "./docs/manifest.json": "./dist/docs/manifest.json"
   },
   "dependencies": {
-    "@metamesh/testkit": "0.16.0",
+    "@metamesh/testkit": "0.17.0",
     "commander": "15.0.0",
     "esbuild": "^0.28.2",
     "playwright": "1.64.1",
@@ -41,8 +41,8 @@
     "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@metamesh/generator-sdk": "0.16.0",
-    "@metamesh/modeling": "0.16.0"
+    "@metamesh/generator-sdk": "0.17.0",
+    "@metamesh/modeling": "0.17.0"
   },
   "peerDependenciesMeta": {
     "@metamesh/generator-sdk": {
@@ -51,8 +51,8 @@
   },
   "devDependencies": {
     "@metamesh/config": "0.0.0",
-    "@metamesh/generator-sdk": "0.16.0",
-    "@metamesh/modeling": "0.16.0",
+    "@metamesh/generator-sdk": "0.17.0",
+    "@metamesh/modeling": "0.17.0",
     "vitest": "^5.0.5",
     "@types/node": "^24.19.2",
     "@types/three": "0.186.0"