@cynodia/axiom-cli 0.16.0-alpha.2 → 0.16.0-alpha.4

package/README.md

@@ -65,10 +65,32 @@ axiom --help
 
 ## Machine-readable output
 
-Pass `--json` on `explain`, `analyze` or `diff` for structured output — parseable,
-deterministic, and semantically identical to the corresponding `AgentAPI` result (no human
-terminal decoration reaches `--json` mode). Everything else prints a concise human-readable
-rendering.
+Pass `--json` on `explain`, `analyze`, `diff` or `validate` for structured output —
+parseable, deterministic, and (for `explain`/`analyze`/`diff`) semantically identical to
+the corresponding `AgentAPI` result (no human terminal decoration reaches `--json` mode).
+Everything else prints a concise human-readable rendering.
+
+**`--json` also governs failure, not only success.** Every CLI-owned error path — an
+unknown node id, a missing required flag, a model file that will not load, an unparseable
+command line — emits one JSON value on stdout instead of prose, and never a native stack
+trace:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "UNKNOWN_NODE",
+    "message": "No action node \"foo\" in this graph"
+  }
+}
+```
+
+`error.code` is one of `INVALID_ARGUMENTS`, `UNKNOWN_COMMAND`, `UNKNOWN_NODE`,
+`MISSING_ARGUMENT`, `MODEL_LOAD_FAILED` or `COMMAND_FAILED` (an uncategorized failure).
+Match on `code`, never on `message` — the same discipline as every other structured
+diagnostic in Axiom. Exit code is always nonzero on failure, in `--json` mode and out of
+it. Without `--json`, error text is unchanged prose on stderr (or, for a handful of
+pre-existing "not found"-style results, stdout — see the source), exactly as before.
 
 ## Exit codes
 

package/dist/index.js

@@ -13,6 +13,30 @@ const SUBCOMMANDS = {
     schema: new Set(['status', 'diff']),
     migrate: new Set(['plan', 'status']),
 };
+/** Thrown for a CLI-level failure that must carry one of the codes above under `--json`. */
+class CliError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * The one shape every CLI-owned failure takes under `--json` (spec16pt4 §4): structured,
+ * deterministic, machine-readable, and — unlike a bare thrown error reaching the top —
+ * carries no native stack trace. Printed to stdout, like every other `--json` result, so a
+ * caller parsing stdout as JSON never has to distinguish success from failure by channel.
+ * Human mode (`options.json` false) is untouched (spec16pt4 §6).
+ */
+function fail(json, code, message) {
+    if (json) {
+        console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
+    }
+    else {
+        console.error(message);
+    }
+    process.exitCode = 1;
+}
 function parseArguments(argv) {
     const positional = [];
     let exportName;
@@ -110,7 +134,13 @@ async function loadGraph(options) {
 async function loadGraphModule(modelFile, exportName) {
     const options = { modelFile, exportName };
     const resolved = path.resolve(process.cwd(), options.modelFile);
-    const module = (await import(pathToFileURL(resolved).href));
+    let module;
+    try {
+        module = (await import(pathToFileURL(resolved).href));
+    }
+    catch (error) {
+        throw new CliError('MODEL_LOAD_FAILED', `Could not load ${options.modelFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const names = options.exportName
         ? [options.exportName]
         : GRAPH_EXPORT_CANDIDATES.filter((name) => name in module);
@@ -131,12 +161,12 @@ async function loadGraphModule(modelFile, exportName) {
             }
         }
         if (builders.length > 1) {
-            throw new Error(`${options.modelFile} exports several candidates. Choose one with --export=<name>: ${builders
+            throw new CliError('MODEL_LOAD_FAILED', `${options.modelFile} exports several candidates. Choose one with --export=<name>: ${builders
                 .map(([name]) => name)
                 .join(', ')}`);
         }
     }
-    throw new Error(`Could not load an application graph from ${options.modelFile}`);
+    throw new CliError('MODEL_LOAD_FAILED', `Could not load an application graph from ${options.modelFile}`);
 }
 const SECTIONS = [
     ['Entities', 'entity'],
@@ -484,7 +514,7 @@ function formatExplanation(kind, result) {
 }
 async function explainCommand(options) {
     if (!options.kind || !options.targetId) {
-        throw new Error('usage: axiom explain <action|query|workflow|state> <id> <modelFile>');
+        throw new CliError('INVALID_ARGUMENTS', 'usage: axiom explain <action|query|workflow|state> <id> <modelFile>');
     }
     const agent = new AgentAPI(await loadGraph(options));
     let result;
@@ -502,11 +532,15 @@ async function explainCommand(options) {
             result = agent.explainState(options.targetId);
             break;
         default:
-            throw new Error(`explain: unknown kind "${options.kind}" (expected action, query, workflow or state)`);
+            throw new CliError('INVALID_ARGUMENTS', `explain: unknown kind "${options.kind}" (expected action, query, workflow or state)`);
     }
     if (!result) {
+        const message = `No ${options.kind} node "${options.targetId}" in this graph`;
+        if (options.json) {
+            throw new CliError('UNKNOWN_NODE', message);
+        }
         process.exitCode = 1;
-        return `No ${options.kind} node "${options.targetId}" in this graph`;
+        return message;
     }
     return options.json ? JSON.stringify(result, null, 2) : formatExplanation(options.kind, result);
 }
@@ -530,7 +564,7 @@ async function analyzeCommand(options) {
 }
 async function diffCommand(options) {
     if (!options.against) {
-        throw new Error('diff needs a --against=<file> naming the graph to compare against');
+        throw new CliError('MISSING_ARGUMENT', 'diff needs a --against=<file> naming the graph to compare against');
     }
     const before = await loadGraphModule(options.against, options.againstExport);
     const after = await loadGraph(options);
@@ -578,16 +612,34 @@ const USAGE = [
 ].join('\n');
 async function main() {
     const argv = process.argv.slice(2);
+    // `--json` may be present even when parsing fails outright (a missing model file, an
+    // unparseable command line), so it is read directly from argv rather than from the
+    // `Options` parseArguments would otherwise have produced (spec16pt4 §3, "missing model
+    // file" / "invalid/missing command arguments").
+    const wantsJson = argv.includes('--json');
     if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {
         console.log(USAGE);
         return;
     }
     const options = parseArguments(argv);
     if (!options) {
-        console.error(USAGE);
-        process.exitCode = 1;
+        if (wantsJson) {
+            fail(true, 'INVALID_ARGUMENTS', 'Missing or invalid command-line arguments. Run "axiom --help" for usage.');
+        }
+        else {
+            console.error(USAGE);
+            process.exitCode = 1;
+        }
         return;
     }
+    try {
+        await runCommand(options);
+    }
+    catch (error) {
+        fail(options.json === true, error instanceof CliError ? error.code : 'COMMAND_FAILED', error instanceof Error ? error.message : String(error));
+    }
+}
+async function runCommand(options) {
     switch (options.command) {
         case 'schema status':
             console.log(schemaStatus(await loadGraph(options)));
@@ -632,11 +684,15 @@ async function main() {
             console.log(await diffCommand(options));
             return;
         default:
-            console.error(`Unknown command: ${options.command}`);
-            process.exitCode = 1;
+            if (options.json) {
+                fail(true, 'UNKNOWN_COMMAND', `Unknown command: ${options.command}`);
+            }
+            else {
+                console.error(`Unknown command: ${options.command}`);
+                process.exitCode = 1;
+            }
     }
 }
 main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    fail(process.argv.slice(2).includes('--json'), error instanceof CliError ? error.code : 'COMMAND_FAILED', error instanceof Error ? error.message : String(error));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-cli",
-  "version": "0.16.0-alpha.2",
+  "version": "0.16.0-alpha.4",
   "description": "Command line tools for inspecting, validating and serving Axiom applications.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -34,12 +34,13 @@
     "axiom": "./dist/index.js"
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.16.0-alpha.2",
-    "@cynodia/axiom-compiler": "0.16.0-alpha.2",
-    "@cynodia/axiom-server": "0.16.0-alpha.2",
-    "@cynodia/axiom-agent-api": "0.16.0-alpha.2"
+    "@cynodia/axiom-core": "0.16.0-alpha.4",
+    "@cynodia/axiom-compiler": "0.16.0-alpha.4",
+    "@cynodia/axiom-server": "0.16.0-alpha.4",
+    "@cynodia/axiom-agent-api": "0.16.0-alpha.4"
   },
   "scripts": {
-    "build": "tsc -b tsconfig.json"
+    "build": "tsc -b tsconfig.json tsconfig.test.json",
+    "test": "node --test dist-test/**/*.test.js"
   }
 }