structured-context 0.10.0 → 0.12.0

package/README.md

@@ -28,10 +28,13 @@ Content and structure
   Schema validation errors                 0
   Broken links                             1
   Duplicate keys                           0
-  Rule violations                          2
+  Rule violations (error)                  0
+  Rule violations (warning)                1
+  Rule violations (info)                   1
   Hierarchy violations                     0
   Orphans (hierarchy nodes - no parent)    1
-  Ignored during parsing                   0
+  Unresolved content links                 0
+  Excluded during parsing                  0
 
 Orphans (hierarchy nodes - no parent):
    Solution looking for a problem.md
@@ -40,13 +43,14 @@ Broken links:
    Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found
 
 Rule violations:
-  workflow (1):
-    Build Death Star.md: Opportunities should contribute to at least one Outcome
-  
-  best-practice (1):
-    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for an active target opportunity
+  WARNING (1):
+    Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome]
+  INFO (1):
+    High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity]
 ```
 
+Rule violations carry a severity (`error`, `warning` or `info`) that defaults from the rule's category. Only errors fail validation — see [docs/rules.md](docs/rules.md#categories-and-severity).
+
 ## Installation
 
 Requires [Bun](https://bun.sh) runtime.
@@ -104,7 +108,7 @@ Schemas define the structure and rules for the entities in a space, allowing cus
 
 Several schemas (`strict_ost`, `knowledge_wiki` and `general`) are included. The general (strategy) schema combines a basic vision/mission/goals hierarchy with a hierarchy loosely based on Opportunity Solution Trees. It is intentionally flexible to support rapid initial adoption. The strict OST schema has a narrower scope, and reflects Teresa Torres' specific recommendations for Opportunity Solution Trees more closely. The knowledge wiki schema defines a flatter set of types used for knowledge bases.
 
-structured-context schemas use a metaschema based on JSON Schema Draft-07 that adds a top-level `$metadata` block:
+structured-context schemas use a metaschema based on JSON Schema 2020-12 that adds a top-level `$metadata` block:
 
 ```json5
 "$metadata": {
@@ -179,23 +183,48 @@ Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a
 
 With `fieldOn: "parent"`, embedded child nodes (parsed from a matching heading's list or table) are appended as wikilinks to the parent's `field` array, rather than receiving a `parent` field. This matches schemas where the content model naturally lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`).
 
-Metadata is composable across `$ref` graphs:
-- `hierarchy`: multiple schema files may define a hierarchy; **last one wins** (root schema overrides partials)
-- `aliases` are shallow-merged (later wins)
-- `rules` merge by `id`; conflicts error unless the later rule sets `override: true`
-- `$metadata.rules` supports `$ref` imports for reusable rule packs
-- `relationships` are collected from all files
+`$ref` reuses JSON Schema definitions for validation only; it brings no metadata. Metadata is composed only through explicit imports:
+
+```json5
+"$metadata": { "imports": ["sctx://core/_strategy_general"] }
+```
+
+- An import brings the whole schema's `$metadata`, and is transitive (the imported schema's own imports come too).
+- Merge order: imports in order, depth-first, then the schema's own metadata last.
+- One rule for every key: a duplicate rule `id`, alias, relationship (same `parent`/`type`/`field`) or hierarchy `name` is an error unless the later entry sets `override: true` (for an alias, write the value as `{ "type": "goal", "override": true }`).
+- `hierarchy`: each schema file declares at most one hierarchy, and every imported hierarchy is kept as a separate named hierarchy (see [Multiple hierarchies](#multiple-hierarchies))
+- Each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it.
 
 If no file defines `hierarchy`, hierarchy-specific checks are skipped.
 
+#### Multiple hierarchies
+
+A space can have several hierarchies by importing schemas that each declare one. For example, a root schema might import a work hierarchy (`goal → task`) and a skills hierarchy (`skill_area → skill`).
+
+- **Naming**: a hierarchy's `name` defaults to the declaring schema's file stem (e.g. `_skills` for `_skills.json`). Set `"name"` in `$metadata.hierarchy` to override it.
+- **Main hierarchy**: if the root schema declares a hierarchy, it is the main one. If the root declares none and exactly one is imported, that one is the main hierarchy. If several are imported, the root must select one:
+
+  ```json5
+  "$metadata": {
+    "imports": ["sctx://_work", "sctx://_skills"],
+    "hierarchy": { "$ref": "sctx://_work#/$metadata/hierarchy" }
+  }
+  ```
+
+  A root may either declare a hierarchy or select one with `$ref`, not both.
+- **Each type belongs to at most one hierarchy.** A type in two hierarchies is an error. To change an imported hierarchy's levels, declare a hierarchy with the same `name` and `"override": true`.
+- **Validation** (layering, parent types, skip levels, orphans) runs per hierarchy. Relationships can connect types across hierarchies.
+- The main hierarchy drives `space_on_a_page` parsing, hierarchy embedding, `template-sync`, and the default `show`/`diagram`/`render` output. Use `--hierarchy <name>` to render another one.
+
 **Customizing Schemas:**
 - **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`).
 - **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content.
-- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata.
-- **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "http://json-schema.org/draft-07/schema#"` so it validates standalone as plain JSON Schema.
-- **Loading priority**: Partial schemas are loaded from both the default schema directory and the directory of your specified target schema.
+- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets that metadata only by listing the partial in `$metadata.imports`.
+- **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "https://json-schema.org/draft/2020-12/schema"` so it validates standalone as plain JSON Schema.
+- **Loading priority**: Partial schemas are loaded from the default schema directory, configured plugins (`schemas/`), and the directory of your specified target schema.
 - **Transitive resolution**: `$ref` chains are resolved recursively across files/schemas (including nested `allOf` usage in partials).
-- **Unique IDs**: To encourage clean namespacing, local partial schemas **must** have unique `$id`s that do not collide with the default schemas. If a collision is detected, validation will fail with an error.
+- **`$id` namespaces**: All `$id`s use `sctx://`. Bundled schemas are `sctx://core/<name>`, plugin schemas `sctx://<pluginName>/<name>`, and local schemas a single name, `sctx://<name>`. Collisions are errors. Legacy bundled ids (`sctx://<name>`, e.g. `sctx://_sctx_base`) resolve to `sctx://core/` with a deprecation warning until 1.0. See [docs/schemas.md](docs/schemas.md#schema-id-namespaces).
+- **Plugin-contributed schemas**: External plugins can contribute schemas via `<pluginRoot>/schemas/` (or `"sctx": { "schemas": "..." }` in `package.json`). Spaces can reference them using `sctx-plugin/schema.json` or `plugin/schema.json`, or by simple filename if the plugin is declared in `plugins`. Schemas resolve statically without executing plugin JavaScript code.
 
 Schema resolution order: space config `schema` > global config `schema`. Schema resolution fails if none is configured.
 
@@ -216,13 +245,24 @@ Validates markdown files against the JSON schema:
 - Skips files without frontmatter or without a `type` field
 - Reports validation results with counts and per-file errors
 
+### Render space
+
+```bash
+sctx render <space> <format> [--out <dir-or-file>] [--force] [--filter <view>] [--hierarchy <name>] [--data key=value]
+```
+
+Renders a space in a plugin-provided format. Use `sctx render list [space]` to list available formats.
+
+- `markdown.bullets` — Indented bullet list tree (outputs to stdout or `--out <file>`).
+- `markdown.directory` — Markdown space directory with one file per node. Writes to `--out <dir>` (refuses to overwrite existing files unless `--force` is passed). Flat directory by default, or organized into per-type subfolders with `--data folders=type` or when configured with `typeInference.folderMap`. Without `--out`, prints a summary of files to be written.
+
 ### Show space tree
 
 ```bash
-sctx show <space> [--filter <view-or-expression>]
+sctx show <space> [--filter <view-or-expression>] [--hierarchy <name>]
 ```
 
-Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes.
+Prints the space as an indented hierarchy tree. Hierarchy roots are listed first, followed by orphans (nodes in the hierarchy but with no resolved parent) and non-hierarchy nodes. The main hierarchy is shown by default; `--hierarchy <name>` selects another (see [Multiple hierarchies](#multiple-hierarchies)). `diagram` and `render` accept the same option.
 
 When a node appears under multiple parents (DAG hierarchy), it is printed in full under its first parent. Subsequent appearances with children show a `(*)` marker indicating the subtree is omitted.
 
@@ -254,6 +294,7 @@ The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression
 - **`ancestors[]`** — flat array of ancestor nodes, nearest first, deduplicated. Each entry includes all schema fields of the ancestor node, plus:
   - `_field` — the edge field name that connects to the ancestor
   - `_source` — `'hierarchy'` or `'relationship'`
+  - `_hierarchy` — the hierarchy name, for hierarchy edges
   - `_selfRef` — whether the edge is a same-type (self-referential) link
 - **`descendants[]`** — same structure, for descendant nodes
 
@@ -304,7 +345,7 @@ SELECT relationships(assumption) WHERE resolvedType='opportunity'
 ### Generate Mermaid diagram
 
 ```bash
-sctx diagram <space> [--output path/to/output.mmd]
+sctx diagram <space> [--output path/to/output.mmd] [--hierarchy <name>]
 ```
 
 Generates a Mermaid `graph TD` diagram from validated space nodes:
@@ -321,7 +362,7 @@ sctx schemas show <schema-file> [--mermaid-erd] [--space <name>]
 
 Generates a Mermaid Entity Relationship Diagram from a schema:
 - Shows all entity types and their properties
-- Displays parent-child relationships based on hierarchy metadata
+- Displays parent-child relationships based on the levels of each hierarchy
 - Useful for visualizing schema structure during development
 
 Example:
@@ -335,13 +376,26 @@ sctx schemas show strategy_general --mermaid-erd
 sctx miro-sync <space> [--new-frame <title>] [--dry-run] [--verbose]
 ```
 
-Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `miroBoardId` set in the space's config entry.
+Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `boardId` set in the `miro` plugin config for the space.
 
-- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `miroFrameId` back to the config file
+- `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `frameId` back to the miro plugin config
 - `--dry-run` — show what would change without touching Miro
 - `--verbose` / `-v` — detailed per-card and per-connector output
 
-On subsequent runs, the cached `miroFrameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
+Configure the miro plugin in the space's config entry:
+
+```json
+{
+  "plugins": {
+    "miro": {
+      "boardId": "your-board-id",
+      "frameId": "your-frame-id"
+    }
+  }
+}
+```
+
+On subsequent runs, the cached `frameId` is used automatically. Cards are colour-coded by node type and linked by parent→child connectors. A local `.miro-cache/` directory tracks Miro IDs to enable incremental updates.
 
 Sync is one-way (OST → Miro) and scoped to a single frame. Only cards and connectors created by this tool within that frame are managed — everything else on the board is left untouched. Card content and connectors are overwritten or recreated to match the markdown source; any edits made directly in Miro to managed cards will be lost on the next sync. Existing card positions are not changed.
 
@@ -357,6 +411,12 @@ Keeps Obsidian template files in sync with schema examples:
 - `templatePrefix` in `plugins.markdown` config (default blank) sets a naming convention for templates (`{templatePrefix}{type}.md`). This will be used to check existing filenames, and create new templates with `--create-missing`.
 - `--dry-run` previews changes without writing files
 
+## Programmatic API
+
+The package exposes a library entry point at `structured-context/api` for embedding the tooling
+in other applications. See
+[docs/api.md](docs/api.md) for the full reference and usage examples.
+
 ## Development
 
 ```bash

package/dist/api.d.ts

@@ -3,13 +3,33 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { validateFile } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
  *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
  */
 export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { Config, SpaceConfig } from './config';
-export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
+export { readSpace } from './read/read-space';
+export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
-export type { SpaceGraph } from './space-graph';
-export type { BaseNode, EdgeDefinition, FileNotInSpaceResult, FileValidationResult, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
-export { validateFile } from './validate';
+export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { buildSpaceGraph, type SpaceGraph } from './space-graph';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, UnresolvedRef, ValidateFileOutput, } from './types';
+export type { ValidationResult } from './validate';
+export { validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -3,7 +3,27 @@
  *
  * Import from this module to use structured-context as a library:
  *
- *   import { validateFile } from 'structured-context/api';
+ *   import { loadConfig, loadSpaceGraph, validateSpace, validateFile } from 'structured-context/api';
  *   import type { StructuredContextPlugin, PluginContext, ParseResult } from 'structured-context/api';
+ *
+ * Common patterns:
+ *
+ *   const config = loadConfig();
+ *   const graph = await loadSpaceGraph('my-space', config, { filter: 'my-view' });
+ *
+ *   // Read once, then assemble a graph and validate from the same read and context:
+ *   const ctx = createSpaceContext('my-space', config);
+ *   const readResult = await readSpace(ctx);
+ *   const graph = await assembleSpaceGraph(ctx, { readResult });
+ *   const validation = await validateSpace(ctx, { readResult });
  */
-export { validateFile } from './validate';
+export { loadConfig, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
+export { PLUGIN_PREFIX } from './constants';
+export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
+export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
+export { readSpace } from './read/read-space';
+export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
+export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
+export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { buildSpaceGraph } from './space-graph';
+export { validateFile, validateSpace } from './validate';

package/dist/commands/diagram.d.ts

@@ -2,4 +2,5 @@ import type { SpaceContext } from '../types';
 export declare function diagram(context: SpaceContext, options: {
     output?: string;
     filter?: string;
+    hierarchy?: string;
 }): Promise<void>;

package/dist/commands/diagram.js

@@ -1,7 +1,13 @@
 import { writeFileSync } from 'node:fs';
 import { executeRender } from '../render/render';
 export async function diagram(context, options) {
-    const result = await executeRender('markdown.mermaid', context, { filter: options.filter });
+    const result = await executeRender('mermaid.graph', context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+    });
+    if (typeof result !== 'string') {
+        throw new Error('Expected string output from mermaid diagram renderer');
+    }
     if (options.output) {
         writeFileSync(options.output, result);
         console.log(`Mermaid diagram written to ${options.output}`);

package/dist/commands/dump.d.ts

@@ -1,2 +1,15 @@
-import type { SpaceContext } from '../types';
-export declare function dump(context: SpaceContext): Promise<void>;
+import type { ReadSpaceResult, SpaceContext } from '../types';
+export interface DumpOptions {
+    /** Named view (resolved via space.views) or a raw filter DSL expression. */
+    filter?: string;
+    /** Hierarchy used when evaluating the filter (default: the main hierarchy). */
+    hierarchy?: string;
+}
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export declare function buildDump(context: SpaceContext, options?: DumpOptions): Promise<ReadSpaceResult>;
+export declare function dump(context: SpaceContext, options?: DumpOptions): Promise<void>;

package/dist/commands/dump.js

@@ -1,6 +1,20 @@
-import JSON5 from 'json5';
+import { assembleSpaceGraph } from '../load-space-graph';
 import { readSpace } from '../read/read-space';
-export async function dump(context) {
-    const { nodes, source, diagnostics } = await readSpace(context);
-    console.log(JSON5.stringify({ nodes, source, diagnostics }, null, 2));
+/**
+ * Build the dump payload: every parsed node, or only nodes matched by a filter.
+ *
+ * Unfiltered dumps include schema-invalid nodes, since dump is a debugging aid.
+ * Filtered dumps match show/render: the filter runs over the graph of schema-valid nodes.
+ */
+export async function buildDump(context, options = {}) {
+    const readResult = await readSpace(context);
+    if (!options.filter)
+        return readResult;
+    const graph = await assembleSpaceGraph(context, { ...options, readResult });
+    const nodes = readResult.nodes.filter((node) => graph.nodes.get(node.title) === node);
+    return { ...readResult, nodes };
+}
+export async function dump(context, options = {}) {
+    const { nodes, source, diagnostics } = await buildDump(context, options);
+    console.log(JSON.stringify({ nodes, source, diagnostics }, null, 2));
 }

package/dist/commands/miro-sync.d.ts

@@ -0,0 +1,3 @@
+import type { SyncOptions } from '../plugins/miro/sync';
+import type { SpaceContext } from '../types';
+export declare function miroSyncCommand(context: SpaceContext, options: SyncOptions): Promise<void>;

package/dist/commands/miro-sync.js

@@ -0,0 +1,8 @@
+import { executeRender } from '../render/render';
+export async function miroSyncCommand(context, options) {
+    const summary = await executeRender('sctx-miro:board', context, {
+        filter: undefined,
+        data: options,
+    });
+    console.log(summary);
+}

package/dist/commands/render.d.ts

@@ -1,6 +1,10 @@
 import type { SpaceContext } from '../types';
 export declare function render(context: SpaceContext, format: string, options: {
     filter?: string;
+    hierarchy?: string;
     output?: string;
+    out?: string;
+    force?: boolean;
+    data?: Record<string, unknown>;
 }): Promise<void>;
 export declare function renderList(context?: SpaceContext): Promise<void>;

package/dist/commands/render.js

@@ -1,17 +1,72 @@
-import { writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { discoverPlugins, loadPlugins } from '../plugins/loader';
+import { isRenderMultiFileOutput } from '../plugins/util';
 import { buildFormatRegistry } from '../render/registry';
 import { executeRender } from '../render/render';
 export async function render(context, format, options) {
-    const result = await executeRender(format, context, { filter: options.filter });
-    if (options.output) {
-        writeFileSync(options.output, result);
-        console.error(`Written to ${options.output}`);
+    const result = await executeRender(format, context, {
+        filter: options.filter,
+        hierarchy: options.hierarchy,
+        data: options.data,
+    });
+    const targetPath = options.out ?? options.output;
+    const force = Boolean(options.force);
+    if (typeof result === 'string') {
+        if (targetPath) {
+            const resolved = resolve(targetPath);
+            if (existsSync(resolved)) {
+                if (statSync(resolved).isDirectory()) {
+                    throw new Error(`Output path "${targetPath}" is a directory. Please specify a file path.`);
+                }
+                if (!force) {
+                    throw new Error(`File "${targetPath}" already exists. Use --force to overwrite.`);
+                }
+            }
+            mkdirSync(dirname(resolved), { recursive: true });
+            writeFileSync(resolved, result, 'utf8');
+            console.error(`Written to ${targetPath}`);
+        }
+        else {
+            process.stdout.write(result);
+            if (!result.endsWith('\n'))
+                process.stdout.write('\n');
+        }
+        return;
     }
-    else {
-        process.stdout.write(result);
-        if (!result.endsWith('\n'))
-            process.stdout.write('\n');
+    if (isRenderMultiFileOutput(result)) {
+        if (targetPath) {
+            const targetDir = resolve(targetPath);
+            const conflicts = [];
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                if (existsSync(fullPath)) {
+                    conflicts.push(file.path);
+                }
+            }
+            if (conflicts.length > 0 && !force) {
+                const preview = conflicts
+                    .slice(0, 5)
+                    .map((f) => `  ${f}`)
+                    .join('\n');
+                const extra = conflicts.length > 5 ? `\n  ... and ${conflicts.length - 5} more` : '';
+                throw new Error(`Refusing to overwrite ${conflicts.length} existing file(s) in "${targetPath}" without --force:\n${preview}${extra}`);
+            }
+            for (const file of result.files) {
+                const fullPath = join(targetDir, file.path);
+                mkdirSync(dirname(fullPath), { recursive: true });
+                writeFileSync(fullPath, file.content, 'utf8');
+            }
+            console.error(`Written ${result.files.length} file(s) to ${targetPath}`);
+        }
+        else {
+            console.log(`Rendered ${result.files.length} file(s):`);
+            for (const file of result.files) {
+                const bytes = Buffer.byteLength(file.content, 'utf8');
+                console.log(`  ${file.path} (${bytes} bytes)`);
+            }
+            console.log('\nSpecify --out <dir> to write files to disk.');
+        }
     }
 }
 export async function renderList(context) {

package/dist/commands/schemas.d.ts

@@ -1,6 +1,6 @@
-export declare function listSchemas(): void;
+export declare function listSchemas(): Promise<void>;
 export declare function showSchema(file: string | undefined, options: {
     space?: string;
     raw: boolean;
     mermaidErd?: boolean;
-}): void;
+}): Promise<void>;