feat: M9 Phase A — API stability surface + error taxonomy #297
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,6 +9,7 @@ import { init, link, view, list, remove, nodes, status, at, importCmd, importMar | |
| import { parseDiffRefs, collectDiffPositionals } from '../src/diff.js'; | ||
| import { createContext } from '../src/context-envelope.js'; | ||
| import { registerBuiltinExtensions } from '../src/extension.js'; | ||
| import { GmindError } from '../src/errors.js'; | ||
|
|
||
| const args = process.argv.slice(2); | ||
| const command = args[0]; | ||
|
|
@@ -114,6 +115,28 @@ Edge types: implements, augments, relates-to, blocks, belongs-to, | |
|
|
||
| const BOOLEAN_FLAGS = new Set(['json', 'fix', 'dry-run', 'validate', 'raw']); | ||
|
|
||
| /** | ||
| * Handle a GmindError at the CLI boundary. | ||
| * Sets exit code and outputs structured JSON when --json is active. | ||
| * Falls back to plain stderr for non-GmindError exceptions. | ||
| * | ||
| * @param {Error} err | ||
| * @param {{ json?: boolean }} [opts] | ||
| */ | ||
| function handleError(err, opts = {}) { | ||
| if (err instanceof GmindError) { | ||
| if (opts.json) { | ||
| console.log(JSON.stringify({ ...err.toJSON(), schemaVersion: 1, command: 'error' }, null, 2)); | ||
| } else { | ||
| console.error(err.message); | ||
| } | ||
| process.exitCode = err.exitCode; | ||
| } else { | ||
| console.error(err.message ?? String(err)); | ||
| process.exitCode = 1; | ||
| } | ||
| } | ||
|
Comment on lines
+118
to
+138
Contributor
There was a problem hiding this comment. 🧹 Nitpick | 🔵 Trivial Hardcoded The If this is a deliberate schema decision (always emit Additionally, for non-GmindError exceptions (line 135), you're accessing 🤖 Prompt for AI Agents
Owner
Author
There was a problem hiding this comment. This is intentional — error envelopes always use
Contributor
There was a problem hiding this comment.
✏️ Learnings added
Comment on lines
+126
to
+138
Contributor
There was a problem hiding this comment. 🧹 Nitpick | 🔵 Trivial
When Consider logging the full stack when a debug flag is present: 🔧 Suggested enhancement } else {
- console.error(err.message ?? String(err));
+ console.error(err.message ?? String(err));
+ if (process.env.GITMIND_DEBUG) console.error(err.stack);
process.exitCode = 1;
}🤖 Prompt for AI Agents |
||
|
|
||
| /** | ||
| * Extract a ContextEnvelope from parsed flags. | ||
| * Builds one only when context flags are present; otherwise returns null. | ||
|
|
@@ -179,8 +202,7 @@ switch (command) { | |
| const source = args[1]; | ||
| const target = args[2]; | ||
| if (!source || !target) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind link <source> <target> [--type <type>]')); | ||
| break; | ||
| } | ||
| const flags = parseFlags(args.slice(3)); | ||
|
|
@@ -209,8 +231,7 @@ switch (command) { | |
| const rmSource = args[1]; | ||
| const rmTarget = args[2]; | ||
| if (!rmSource || !rmTarget) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind remove <source> <target> [--type <type>]')); | ||
| break; | ||
| } | ||
| const rmFlags = parseFlags(args.slice(3)); | ||
|
|
@@ -246,9 +267,9 @@ switch (command) { | |
| const setKey = args[2]; | ||
| const setValue = args[3]; | ||
| if (!setNodeId || !setKey || setValue === undefined || setValue.startsWith('--')) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind set <nodeId> <key> <value> [--json]', { | ||
| hint: '<value> is positional and required (flags are not valid values)', | ||
| }), { json: args.includes('--json') }); | ||
| break; | ||
|
Comment on lines
+270
to
273
Contributor
There was a problem hiding this comment. 🧹 Nitpick | 🔵 Trivial Passing You parse flags with For consistency, consider using ♻️ Proposed refactor case 'set': {
const setNodeId = args[1];
const setKey = args[2];
const setValue = args[3];
+ const setFlags = parseFlags(args.slice(4));
+ const jsonMode = setFlags.json === true;
if (!setNodeId || !setKey || setValue === undefined || setValue.startsWith('--')) {
handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind set <nodeId> <key> <value> [--json]', {
hint: '<value> is positional and required (flags are not valid values)',
- }), { json: args.includes('--json') });
+ }), { json: jsonMode });
break;
}
- await set(cwd, setNodeId, setKey, setValue, { json: args.includes('--json') });
+ await set(cwd, setNodeId, setKey, setValue, { json: jsonMode });
break;
}🤖 Prompt for AI Agents |
||
| } | ||
| await set(cwd, setNodeId, setKey, setValue, { json: args.includes('--json') }); | ||
|
|
@@ -259,8 +280,7 @@ switch (command) { | |
| const unsetNodeId = args[1]; | ||
| const unsetKey = args[2]; | ||
| if (!unsetNodeId || !unsetKey) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind unset <nodeId> <key>'), { json: args.includes('--json') }); | ||
| break; | ||
| } | ||
| await unsetCmd(cwd, unsetNodeId, unsetKey, { json: args.includes('--json') }); | ||
|
|
@@ -280,8 +300,7 @@ switch (command) { | |
| case 'at': { | ||
| const atRef = args[1]; | ||
| if (!atRef || atRef.startsWith('--')) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind at <ref>'), { json: args.includes('--json') }); | ||
| break; | ||
| } | ||
| await at(cwd, atRef, { json: args.includes('--json') }); | ||
|
|
@@ -298,8 +317,10 @@ switch (command) { | |
| prefix: diffFlags.prefix, | ||
| }); | ||
| } catch (err) { | ||
| handleError( | ||
| err instanceof GmindError ? err : new GmindError('GMIND_E_USAGE', err.message, { cause: err }), | ||
| { json: diffFlags.json }, | ||
| ); | ||
| } | ||
| break; | ||
| } | ||
|
|
@@ -316,8 +337,7 @@ switch (command) { | |
|
|
||
| const importPath = args.slice(1).find(a => !a.startsWith('--')); | ||
| if (!importPath) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind import <file> [--dry-run] [--json] [--from-markdown <glob>]'), { json: jsonMode }); | ||
| break; | ||
| } | ||
| await importCmd(cwd, importPath, { dryRun, json: jsonMode }); | ||
|
|
@@ -355,8 +375,7 @@ switch (command) { | |
|
|
||
| case 'process-commit': | ||
| if (!args[1]) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind process-commit <sha>')); | ||
| break; | ||
| } | ||
| await processCommitCmd(cwd, args[1]); | ||
|
|
@@ -403,8 +422,7 @@ switch (command) { | |
| const setNode = contentPositionals[0]; | ||
| const fromFile = contentFlags.from; | ||
| if (!setNode || !fromFile) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind content set <node> --from <file> [--mime <type>] [--json]'), { json: contentFlags.json }); | ||
| break; | ||
| } | ||
| await contentSet(cwd, setNode, fromFile, { | ||
|
|
@@ -416,8 +434,7 @@ switch (command) { | |
| case 'show': { | ||
| const showNode = contentPositionals[0]; | ||
| if (!showNode) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind content show <node> [--raw] [--json]'), { json: contentFlags.json }); | ||
| break; | ||
| } | ||
| await contentShow(cwd, showNode, { | ||
|
|
@@ -429,8 +446,7 @@ switch (command) { | |
| case 'meta': { | ||
| const metaNode = contentPositionals[0]; | ||
| if (!metaNode) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind content meta <node> [--json]'), { json: contentFlags.json }); | ||
| break; | ||
| } | ||
| await contentMeta(cwd, metaNode, { json: contentFlags.json ?? false }); | ||
|
|
@@ -439,17 +455,16 @@ switch (command) { | |
| case 'delete': { | ||
| const deleteNode = contentPositionals[0]; | ||
| if (!deleteNode) { | ||
| handleError(new GmindError('GMIND_E_USAGE', 'Usage: git mind content delete <node> [--json]'), { json: contentFlags.json }); | ||
| break; | ||
| } | ||
| await contentDelete(cwd, deleteNode, { json: contentFlags.json ?? false }); | ||
| break; | ||
| } | ||
| default: | ||
| handleError(new GmindError('GMIND_E_UNKNOWN_CMD', `Unknown content subcommand: ${contentSubCmd ?? '(none)'}`, { | ||
| hint: 'Usage: git mind content <set|show|meta|delete>', | ||
| }), { json: contentFlags.json ?? false }); | ||
| } | ||
| break; | ||
| } | ||
|
|
@@ -478,9 +493,9 @@ switch (command) { | |
| break; | ||
| } | ||
| default: | ||
| handleError(new GmindError('GMIND_E_UNKNOWN_CMD', `Unknown extension subcommand: ${subCmd ?? '(none)'}`, { | ||
| hint: 'Usage: git mind extension <list|validate|add|remove>', | ||
| }), { json: extFlags.json ?? false }); | ||
| } | ||
| break; | ||
| } | ||
|
|
@@ -491,11 +506,15 @@ switch (command) { | |
| printUsage(); | ||
| break; | ||
|
|
||
| default: { | ||
| // No command: show usage (plain text) or exit silently (--json) with code 0. | ||
| const jsonMode = args.includes('--json'); | ||
| if (command) { | ||
| handleError(new GmindError('GMIND_E_UNKNOWN_CMD', `Unknown command: ${command}`), { json: jsonMode }); | ||
| if (!jsonMode) console.error(''); | ||
| } | ||
| if (!jsonMode) printUsage(); | ||
| if (!command) process.exitCode = 0; | ||
| break; | ||
| } | ||
coderabbitai[bot] marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| { | ||
| "name": "@neuroglyph/git-mind", | ||
| "version": "5.1.1", | ||
| "description": "A project knowledge graph tool built on git-warp", | ||
| "type": "module", | ||
| "license": "Apache-2.0", | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.