refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
@@ -1,8 +1,8 @@
|
||||
# JSON Error Mode — `gsd-tools` Structured Errors
|
||||
# JSON Error Mode — `msd-tools` Structured Errors
|
||||
|
||||
## Overview
|
||||
|
||||
`gsd-tools` supports a **JSON error mode** that emits most errors as structured
|
||||
`msd-tools` supports a **JSON error mode** that emits most errors as structured
|
||||
JSON objects on stderr instead of free-form text. This is the recommended
|
||||
surface for tests and tooling that need to assert on error types without
|
||||
grepping raw text (see `CONTRIBUTING.md` — "Prohibited: Raw Text Matching on
|
||||
@@ -13,7 +13,7 @@ Test Outputs"). Usage errors are an intentional exception — see the
|
||||
> intentional one reports conditions in the **result payload on stdout with
|
||||
> exit 0**. A caller that branches on exit status alone will not see it. Read
|
||||
> [Degraded results vs faults](#degraded-results-vs-faults--read-this-before-writing-a-caller)
|
||||
> before writing anything that consumes `gsd-tools` output.
|
||||
> before writing anything that consumes `msd-tools` output.
|
||||
|
||||
## Activating
|
||||
|
||||
@@ -21,10 +21,10 @@ Either flag or env var activates the mode:
|
||||
|
||||
```bash
|
||||
# Flag (preferred in test code):
|
||||
node gsd-tools.cjs --json-errors <command> [args]
|
||||
node msd-tools.cjs --json-errors <command> [args]
|
||||
|
||||
# Env var (preferred for shell wrappers and CI):
|
||||
GSD_JSON_ERRORS=1 node gsd-tools.cjs <command> [args]
|
||||
MSD_JSON_ERRORS=1 node msd-tools.cjs <command> [args]
|
||||
```
|
||||
|
||||
## Wire format
|
||||
@@ -59,7 +59,7 @@ assert on the exit code and (if needed) the plain-text message. The
|
||||
branch (non-`ExitError` failures).
|
||||
|
||||
> **Which tools honor this.** Both surfaces that run `runMain` do: the compiled
|
||||
> `gsd-core/bin/lib/cli-exit.cjs` and the `scripts/lib/cli-exit.cjs` that the
|
||||
> `msd-core/bin/lib/cli-exit.cjs` and the `scripts/lib/cli-exit.cjs` that the
|
||||
> repo's own `scripts/**` tooling requires. Before [#3904](https://github.com/open-gsd/gsd-core/issues/3904)
|
||||
> the latter was a separate hand-written copy that never gained the
|
||||
> structured-envelope branch, so a `scripts/`-side tool failing unexpectedly
|
||||
@@ -69,7 +69,7 @@ branch (non-`ExitError` failures).
|
||||
|
||||
## Degraded results vs faults — read this before writing a caller
|
||||
|
||||
`gsd-tools` has **two** ways of telling you something went wrong, and they use **different exit
|
||||
`msd-tools` has **two** ways of telling you something went wrong, and they use **different exit
|
||||
codes**. The wire format above describes only one of them. If you write a caller that branches on
|
||||
exit status alone, you will silently miss the other.
|
||||
|
||||
@@ -87,7 +87,7 @@ result.* It is not a process failure. The command succeeded at the job of determ
|
||||
example, the artifact you asked about is absent.
|
||||
|
||||
```console
|
||||
$ gsd-tools state-snapshot # in a project with no STATE.md
|
||||
$ msd-tools state-snapshot # in a project with no STATE.md
|
||||
{
|
||||
"error": "STATE.md not found"
|
||||
}
|
||||
@@ -99,7 +99,7 @@ Some verbs return a companion result alongside the key, which is the shape that
|
||||
clearest:
|
||||
|
||||
```console
|
||||
$ gsd-tools roadmap get-phase --phase 1 # no ROADMAP.md
|
||||
$ msd-tools roadmap get-phase --phase 1 # no ROADMAP.md
|
||||
{
|
||||
"found": false,
|
||||
"error": "ROADMAP.md not found"
|
||||
@@ -124,7 +124,7 @@ The obvious shell form is **wrong** for a degraded result:
|
||||
|
||||
```sh
|
||||
# WRONG — the process exits 0, so this branch never runs
|
||||
if ! gsd-tools state-snapshot > snap.json; then
|
||||
if ! msd-tools state-snapshot > snap.json; then
|
||||
echo "failed"
|
||||
fi
|
||||
```
|
||||
@@ -132,7 +132,7 @@ fi
|
||||
Check both channels — the exit code for faults, the payload for degraded results:
|
||||
|
||||
```sh
|
||||
if ! out=$(gsd-tools state-snapshot); then
|
||||
if ! out=$(msd-tools state-snapshot); then
|
||||
echo "fault (exit non-zero)" >&2 # error() path
|
||||
exit 1
|
||||
fi
|
||||
@@ -149,8 +149,8 @@ fi
|
||||
the JSON object rather than bare text — but eleven sites do pass one and behave differently.
|
||||
Do not infer either behavior from `--raw` alone; check the verb.
|
||||
3. **Not every degraded result is an absent artifact.** A missing required argument is reported the
|
||||
same way — `gsd-tools state add-blocker` with no `--text` returns `{"error":"text required"}` and
|
||||
exits 0. So is unusable input: `gsd-tools state advance-plan` against a STATE.md it cannot parse
|
||||
same way — `msd-tools state add-blocker` with no `--text` returns `{"error":"text required"}` and
|
||||
exits 0. So is unusable input: `msd-tools state advance-plan` against a STATE.md it cannot parse
|
||||
returns an `{"error": …}` naming the plan-position shapes it accepts (the list is derived from
|
||||
`STATE_FIELD_SCHEMA.current_plan.acceptedShapes`, so do not quote it verbatim), also exit
|
||||
0. **The exit code does not distinguish absent from malformed from misinvoked** — see ADR-2980's
|
||||
@@ -166,7 +166,7 @@ non-fatal condition in its payload, prefer the shape `state update-progress` alr
|
||||
field plus a reason, with no overloaded `error` key:
|
||||
|
||||
```console
|
||||
$ gsd-tools state update-progress # STATE.md present, no Progress field
|
||||
$ msd-tools state update-progress # STATE.md present, no Progress field
|
||||
{
|
||||
"updated": false,
|
||||
"reason": "Progress field not found in STATE.md"
|
||||
@@ -179,7 +179,7 @@ Both failure channels above now **declare an outcome** on every terminating path
|
||||
[ADR-3889](adr/3889-process-exit-contract.md). Declaration is unconditional; whether it changes the
|
||||
observed exit code depends on which **exit-contract version** the process is running under.
|
||||
|
||||
Turn on `v2` with either `--exit-contract=v2` or `GSD_EXIT_CONTRACT=v2` (a flag beats the env var if
|
||||
Turn on `v2` with either `--exit-contract=v2` or `MSD_EXIT_CONTRACT=v2` (a flag beats the env var if
|
||||
both are given). Absent either, the process runs `v1` — today's default and, for every existing
|
||||
caller, byte-identical to pre-#3912 behavior. See
|
||||
[Adopt the v2 exit contract](how-to/adopt-the-v2-exit-contract.md) for a worked migration.
|
||||
@@ -242,17 +242,17 @@ later `runMain` call in the same process never inherits a stale declaration.
|
||||
|
||||
## Error code taxonomy
|
||||
|
||||
Codes are frozen constants in `gsd-core/bin/lib/core.cjs` under
|
||||
Codes are frozen constants in `msd-core/bin/lib/core.cjs` under
|
||||
`ERROR_REASON`. Tests must assert on `reason` values (stable), not `message`
|
||||
text (unstable).
|
||||
|
||||
### Dispatch errors (gsd-tools routing layer)
|
||||
### Dispatch errors (msd-tools routing layer)
|
||||
|
||||
| Code | When emitted |
|
||||
|------|-------------|
|
||||
| `sdk_unknown_command` | Unknown top-level command (`gsd-tools bogus-cmd`) |
|
||||
| `sdk_unknown_command` | Unknown dotted command (`gsd-tools foo.bar` where `foo` is not a known command) |
|
||||
| `sdk_unknown_command` | Unknown subcommand within a domain (e.g. `gsd-tools intel bogus-sub`) |
|
||||
| `sdk_unknown_command` | Unknown top-level command (`msd-tools bogus-cmd`) |
|
||||
| `sdk_unknown_command` | Unknown dotted command (`msd-tools foo.bar` where `foo` is not a known command) |
|
||||
| `sdk_unknown_command` | Unknown subcommand within a domain (e.g. `msd-tools intel bogus-sub`) |
|
||||
| `sdk_missing_arg` | Required argument omitted by an SDK-level guard |
|
||||
| `sdk_fail_fast` | SDK fail-fast policy triggered |
|
||||
|
||||
@@ -261,7 +261,7 @@ text (unstable).
|
||||
| Code | When emitted |
|
||||
|------|-------------|
|
||||
| `usage` | `--pick` flag used without a following value |
|
||||
| `usage` | Version flag (`--version`, `-v`) which gsd-tools never accepts |
|
||||
| `usage` | Version flag (`--version`, `-v`) which msd-tools never accepts |
|
||||
| `usage` | Top-level no-args invocation (usage text) |
|
||||
|
||||
### `--pick <field>` errors (ADR-3473 §8.4, #3884)
|
||||
@@ -321,7 +321,7 @@ or regex on the raw error string.
|
||||
|
||||
```js
|
||||
// CORRECT: parse then assert on typed field
|
||||
const result = runGsdTools(['--json-errors', 'bogus-command'], tmpDir);
|
||||
const result = runMsdTools(['--json-errors', 'bogus-command'], tmpDir);
|
||||
assert.strictEqual(result.success, false);
|
||||
const err = JSON.parse(result.error);
|
||||
assert.strictEqual(err.ok, false);
|
||||
@@ -334,7 +334,7 @@ assert.strictEqual(err.reason, 'sdk_unknown_command');
|
||||
## Adding a new error code
|
||||
|
||||
1. Add the constant to `ERROR_REASON` in
|
||||
`gsd-core/bin/lib/core.cjs` (snake\_case, prefixed by subsystem).
|
||||
`msd-core/bin/lib/core.cjs` (snake\_case, prefixed by subsystem).
|
||||
2. Pass it as the second argument to `error()` at the call site.
|
||||
3. Add a row to this document.
|
||||
4. Add a test asserting the new `reason` code via `JSON.parse`.
|
||||
|
||||
Reference in New Issue
Block a user