@ontrails/commander 1.0.0-beta.16 → 1.0.0-beta.17

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ontrails/commander
 
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+- Updated dependencies [61497c5]
+  - @ontrails/core@1.0.0-beta.17
+  - @ontrails/cli@1.0.0-beta.17
+
 ## 1.0.0-beta.16
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/commander",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.17",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,8 +22,8 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/cli": "^1.0.0-beta.15",
-    "@ontrails/core": "^1.0.0-beta.15",
+    "@ontrails/cli": "^1.0.0-beta.16",
+    "@ontrails/core": "^1.0.0-beta.16",
     "commander": "^14.0.3"
   },
   "peerDependencies": {

package/src/surface.ts

@@ -68,6 +68,14 @@ const deriveCommanderOptions = (
  * @remarks This is a host materialization boundary. Derivation failures are
  * thrown for the caller's CLI bootstrap code after `deriveCliCommands` has
  * already represented the framework error as a Result.
+ *
+ * @example
+ * ```ts
+ * import { createProgram } from '@ontrails/commander';
+ *
+ * const program = createProgram(graph, { name: 'demo' });
+ * program.parse();
+ * ```
  */
 export const createProgram = (
   graph: Topo,
@@ -108,6 +116,13 @@ export const createProgram = (
  * Returns the process exit code without calling `process.exit()`, so callers
  * can run cleanup before terminating. The CLI `surface()` entry point
  * delegates here and lets the process exit naturally.
+ *
+ * @example
+ * ```ts
+ * import { surface } from '@ontrails/commander';
+ *
+ * const { exitCode } = await surface(graph, { name: 'demo' });
+ * ```
  */
 export const surface = async (
   graph: Topo,

package/src/to-commander.ts

@@ -438,6 +438,20 @@ const applyCliCommand = (
   state.executable = true;
 };
 
+/**
+ * Convert framework-agnostic CLI commands into a Commander program.
+ *
+ * @example
+ * ```ts
+ * import { deriveCliCommands } from '@ontrails/cli';
+ * import { toCommander } from '@ontrails/commander';
+ *
+ * const commands = deriveCliCommands(graph);
+ * if (commands.isErr()) throw commands.error;
+ *
+ * const program = toCommander(commands.value, { name: 'demo' });
+ * ```
+ */
 export const toCommander = (
   commands: CliCommand[],
   options?: ToCommanderOptions