burgee 0.9.2 → 0.10.0

package/dist/execute.js

@@ -326,6 +326,7 @@ async function surface(manifest, argv, io) {
         return true;
     }
     if (head.includes('--schema')) {
+        const { schemaSurface } = await import('./schema-surface.js');
         io.out.write(`${await machineJson(await schemaSurface(manifest, argv), head)}\n`);
         return true;
     }
@@ -351,16 +352,6 @@ async function surface(manifest, argv, io) {
     }
     return false;
 }
-const SCHEMA_BUDGET = 48_000;
-async function schemaSurface(manifest, argv) {
-    const { commandSchemaOf, schemaOf, summaryOf } = await import('./schema.js');
-    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema' && !a.startsWith('--format=')), manifest.rootPath);
-    if (node?.run !== undefined)
-        return commandSchemaOf(node, manifest.rootPath);
-    const full = schemaOf(manifest);
-    const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
-    return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
-}
 async function helpCommand(manifest, argv, root, io) {
     const { node } = manifest.resolve(argv, root);
     return renderHelp(manifest, node ?? rootNode(manifest, root), io);

package/dist/schema-surface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * N13 / D-116 — `--schema <command> --field <path>`: one field of one command's schema, so an
+ * agent under a token budget reads `options.region` instead of the whole document. The path is
+ * dotted; a step that does not exist is refused naming the steps that do.
+ *
+ * With the `--schema` surface it serves: `execute.ts` imports this module only when `--schema`
+ * is on the command line (M2), so neither weighs on a run that does not ask for it.
+ */
+import { type Manifest } from './manifest.js';
+export declare function fieldOf(doc: unknown, path: string, command: string): unknown;
+/**
+ * `--schema` under a character budget (N13): one command's full schema when a command is
+ * named (the drilling), the whole program when it fits, a summary naming every command
+ * and how to drill when it does not.
+ */
+export declare function schemaSurface(manifest: Manifest, argv: string[]): Promise<unknown>;

package/dist/schema-surface.js

@@ -0,0 +1,38 @@
+import { UsageError } from './validate.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function fieldOf(doc, path, command) {
+    let at = doc;
+    const walked = [];
+    for (const step of path.split('.')) {
+        if (!isRecord(at) || !(step in at)) {
+            const here = walked.length === 0 ? `"${command}"` : `"${walked.join('.')}"`;
+            const valid = isRecord(at) ? Object.keys(at).join(', ') : 'none — it is a value';
+            throw new UsageError(`${here} has no field "${step}"`, `fields here: ${valid}`);
+        }
+        at = at[step];
+        walked.push(step);
+    }
+    return at;
+}
+const SCHEMA_BUDGET = 48_000;
+export async function schemaSurface(manifest, argv) {
+    const { commandSchemaOf, schemaOf, summaryOf } = await import('./schema.js');
+    const end = argv.indexOf('--');
+    const head = end === -1 ? argv : argv.slice(0, end);
+    const at = head.findIndex((a) => a === '--field' || a.startsWith('--field='));
+    const field = at === -1 ? undefined : (head[at]?.slice('--field='.length) || head[at + 1]);
+    const width = head[at] === '--field' ? 1 : 0;
+    const drop = at === -1 ? -1 : at + width;
+    const path = head.filter((a, i) => a !== '--schema' && !a.startsWith('--format=') && (i < at || i > drop));
+    const { node } = manifest.resolve(path, manifest.rootPath);
+    if (field !== undefined) {
+        if (node?.run === undefined)
+            throw new UsageError('--field drills into one command', 'name the command first: --schema <command> --field <path>');
+        return fieldOf(commandSchemaOf(node, manifest.rootPath), field, path.join(' '));
+    }
+    if (node?.run !== undefined)
+        return commandSchemaOf(node, manifest.rootPath);
+    const full = schemaOf(manifest);
+    const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
+    return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -147,8 +147,8 @@
   },
   "dependencies": {
     "bellpull": "^0.2.2",
-    "closeout": "^0.3.2",
-    "linegauge": "^0.4.2",
+    "closeout": "^0.4.0",
+    "linegauge": "^0.4.3",
     "roundel": "^0.4.2",
     "seniority": "^0.4.2"
   },