feat(cli): deprecate validate, inspect, layout in favor of check

One stderr notice per invocation and _meta.deprecated: true in JSON mode
(shared helper next to withMeta; layout owns both inspect and layout via
createInspectCommand). Help descriptions gain the pointer. No behavior
change; removal ships separately once migration telemetry says usage
has decayed.

fix(producer): route info/debug logs to stderr — the compiler's
'Localized remote media' line was landing on stdout ahead of validate's
--json payload, breaking every piped consumer. Diagnostics now share
stderr with warn/error; render progress uses its own channel.
This commit is contained in:
Miguel Angel Simon Sierra
2026-07-10 13:27:52 -04:00
parent 3a02942a03
commit 58f45ef758
9 changed files with 500 additions and 86 deletions
+25 -2
View File
@@ -40,6 +40,8 @@ export interface UpdateMeta {
version: string;
latestVersion?: string;
updateAvailable: boolean;
/** Present (and true) only for commands superseded by `check`; absent otherwise. */
deprecated?: boolean;
}
/**
@@ -130,9 +132,30 @@ export function getUpdateMeta(): UpdateMeta {
/**
* Wrap a JSON payload with the _meta version envelope.
* Use this in all --json command outputs for consistent agent-friendly metadata.
*
* Pass `{ deprecated: true }` from a command superseded by `check` (validate,
* inspect, layout) to add `_meta.deprecated: true`; every other call site is
* unaffected — the key is only ever added, never set to `false`.
*/
export function withMeta<T extends object>(data: T): T & { _meta: UpdateMeta } {
return { ...data, _meta: getUpdateMeta() };
export function withMeta<T extends object>(
data: T,
options?: { deprecated?: boolean },
): T & { _meta: UpdateMeta } {
const meta = getUpdateMeta();
if (options?.deprecated) meta.deprecated = true;
return { ...data, _meta: meta };
}
/**
* One-line deprecation notice for a command superseded by `check`. Always
* writes to stderr (never stdout), so a --json invocation's stdout stays
* pure, parseable JSON. Call once per invocation, before the command's own
* output.
*/
export function printDeprecationNotice(command: string): void {
process.stderr.write(
`'hyperframes ${command}' is deprecated and will be removed in a future release. Use 'hyperframes check' instead.\n`,
);
}
/**