2d14eb8873
* test(#177): add DispatchEvent factory failing tests Red tests for makeDispatchEvent shape, traceId UUID v4, uniqueness, parentTraceId-always-undefined (P1.3), args redaction toggle, ISO 8601 timestamp, and all result variant passthrough. * feat(#177): introduce DispatchEvent factory makeDispatchEvent produces an immutable event record per dispatch: - traceId: crypto.randomUUID() (UUID v4) - parentTraceId: always undefined (P1.4 wires composer) - command, result, timestamp (ISO 8601) - args only included when includeArgs === true (default: omitted) * test(#177): add arg redaction policy failing tests Red tests for shouldIncludeArgs (GSD_AUDIT_ARGS env gating) and redactEvent (strips args from frozen events, preserves all other fields, returns a new object, never mutates the source). * feat(#177): introduce arg redaction policy shouldIncludeArgs(): only GSD_AUDIT_ARGS==='1' opts in; all other values (unset, '', '0', 'true') default to omitting args. redactEvent(event): returns a shallow copy of the event, dropping the args field unless opted in. Never mutates the (frozen) source event. * test(#177): add DispatchLogger interface failing tests Red tests covering: - no-op logger: silent on all events, never throws - default logger: silent on ok, one flattened JSON line to stderr on error - default logger: audit file creation + append-only + redaction + config gate - GSD_AUDIT env var and config.audit.enabled config gate - GSD_AUDIT_ARGS opt-in for args inclusion All tests use real fs under os.tmpdir() — no mocked appendFileSync. * feat(#177): introduce DispatchLogger with default and no-op implementations createNoOpLogger(): silent on all events — Hub default when no logger injected. createDefaultLogger({ cwd, config }): - Silent on ok result - Flattened JSON line to stderr on error: { kind, traceId, ...typedPayload } - Append-only audit at .planning/.gsd-trace.jsonl when GSD_AUDIT=1 or config.audit.enabled - Args redacted by default; GSD_AUDIT_ARGS=1 opts in - Logger errors caught internally; never break dispatch callers * test(#177): add Hub+logger integration failing tests Red tests verifying: - onEvent called exactly once per dispatch (ok, error, handler-throw, unknown) - DispatchEvent shape: traceId uniqueness, command, result.kind, parentTraceId - Logger errors contained (dispatch still returns Result, warn line to stderr) - Hub defaults to no-op when no logger injected - End-to-end with createDefaultLogger: silent on success, stderr on error, audit file * feat(#177): wire DispatchLogger into CommandRoutingHub Add optional logger param to createHub({ ..., logger }). Defaults to createNoOpLogger() — silent, no behaviour change for callers that don't inject a logger. After every dispatch (success and error): - Normalises HubResult { ok } to DispatchEvent { kind: 'ok'|error-kind } - Calls makeDispatchEvent({ command, args, result }) to mint the event - Calls logger.onEvent(event) exactly once - Wraps in try/catch: logger errors emit { level:'warn', source:'DispatchLogger' } to stderr but never propagate to dispatch callers * chore(#177): gitignore .planning/.gsd-trace.jsonl audit file The audit trail is local-only, append-only, and must never be committed. Slotted under the existing "Local scratch + Claude-test artifacts" block. * docs(#177): document GSD_AUDIT, GSD_AUDIT_ARGS, config.audit.enabled New ## Observability section at end of CONFIGURATION.md covering: - Default silent/stderr behaviour overview - Stderr error JSON format - Audit file opt-in (env var and config key) - Args redaction policy and GSD_AUDIT_ARGS opt-in Also slots GSD_AUDIT and GSD_AUDIT_ARGS into the existing ## Environment Variables table (alphabetical order). * chore(#177): add changeset for observability seam type: Added — new DispatchLogger seam with default silent/stderr/audit behaviour.
51 lines
1.7 KiB
JavaScript
51 lines
1.7 KiB
JavaScript
'use strict';
|
|
|
|
/**
|
|
* Arg redaction policy — issue #177 (ADR-0174 P1.3).
|
|
*
|
|
* Privacy default: args are OMITTED from every emitted event (both stderr
|
|
* and file audit). Opt-in: set GSD_AUDIT_ARGS=1 to include args verbatim.
|
|
*
|
|
* This module is deliberately simple and has no side effects — redaction
|
|
* decisions are stateless reads of process.env at call time so that tests
|
|
* can toggle the env var without module-level caching issues.
|
|
*/
|
|
|
|
/**
|
|
* Returns true when the caller has opted in to including args in events.
|
|
* Only GSD_AUDIT_ARGS === '1' enables inclusion; any other value (including
|
|
* empty string, 'true', 'yes') keeps the default of omitting args.
|
|
*
|
|
* @returns {boolean}
|
|
*/
|
|
function shouldIncludeArgs() {
|
|
return process.env.GSD_AUDIT_ARGS === '1';
|
|
}
|
|
|
|
/**
|
|
* Return a redacted copy of a DispatchEvent.
|
|
*
|
|
* If args should be omitted (default), strips the `args` field entirely.
|
|
* If args should be included (GSD_AUDIT_ARGS=1), passes the event through
|
|
* unchanged (args were already set by makeDispatchEvent with includeArgs:true,
|
|
* or absent — in which case they stay absent).
|
|
*
|
|
* The original event object is never mutated (it is frozen by makeDispatchEvent).
|
|
*
|
|
* @param {object} event - A DispatchEvent (frozen or plain).
|
|
* @returns {object} A new plain object with the same fields, minus args when redacted.
|
|
*/
|
|
function redactEvent(event) {
|
|
if (shouldIncludeArgs()) {
|
|
// Include path: return a shallow copy with args preserved if present
|
|
const copy = Object.assign({}, event);
|
|
return copy;
|
|
}
|
|
|
|
// Exclude path: build a copy omitting `args`
|
|
const { args: _dropped, ...rest } = event;
|
|
return rest;
|
|
}
|
|
|
|
module.exports = { shouldIncludeArgs, redactEvent };
|