diff --git a/project-management/Roadmap/epics/archive/logging-modernisation.md b/project-management/Roadmap/epics/archive/logging-modernisation.md new file mode 100644 index 0000000..4688064 --- /dev/null +++ b/project-management/Roadmap/epics/archive/logging-modernisation.md @@ -0,0 +1,36 @@ +# Epic: Logging Modernisation + +## Status +Done — completed 2026-06-28 + +## Why now +Issue #4 from a community user reports 8 lines of console output per keystroke in the template field. The root cause is a hardcoded `logger.setLevel(logging.DEBUG)` at module level combined with diagnostic `print()` blocks that were never removed after the FormatString output-order fix. Left unaddressed this makes the nodes unusable in production ComfyUI sessions. This is also a correctness issue: a library must never configure its own log level or add handlers — that violates the Python logging best-practice contract. + +## Dependencies +_None._ + +## Specs + + +- specs/001-standardise-logging/ +## ADRs + +- [ADR-001](../../ADRs/ADR-001-stdlib-logging-over-console-libraries.md) — stdlib logging over colored console libraries +- [ADR-002](../../ADRs/ADR-002-nullhandler-pattern-for-library-loggers.md) — NullHandler pattern for library loggers + +## Success criteria +- [x] `logger.setLevel(logging.DEBUG)` removed from all modules; log level controlled entirely by the host (ComfyUI or the user's logging config) +- [x] `logging.NullHandler()` added to the package root logger in `__init__.py` +- [x] All diagnostic `print()` calls converted to `logger.debug()` / `logger.info()` / `logger.error()` as appropriate +- [x] `colorama`, `termcolor`, and `rich` removed from runtime dependencies in `pyproject.toml` (they are only used for the now-deleted console-print logging) +- [x] A normal ComfyUI run produces zero output from this package unless the host enables DEBUG +- [x] Errors (template render failures, file-save failures, interrupt triggers) still surface at `ERROR` / `INFO` level +- [x] All existing tests pass; no new test failures introduced + +## Non-goals +- Not adding a user-facing log-level toggle inside ComfyUI's UI +- Not changing node behaviour, output structure, or ComfyUI API contracts +- Not adding structured/JSON logging + +## Notes +The `IS_CHANGED` and `update_widget` methods fire on every keystroke via the JS → aiohttp route. Any log call at INFO or above in these hot paths will be visible to the user. All calls in these hot paths must be DEBUG or removed. diff --git a/project-management/Roadmap/epics/ux-and-install.md b/project-management/Roadmap/epics/ux-and-install.md index f6e7b1e..dc06142 100644 --- a/project-management/Roadmap/epics/ux-and-install.md +++ b/project-management/Roadmap/epics/ux-and-install.md @@ -21,6 +21,10 @@ _None — this epic is self-contained and can start immediately._ +- specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/ +- specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/ +- specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/ +- specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/ ## ADRs _To be recorded as cross-cutting decisions are made during DESIGN._ diff --git a/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/.beacon.toml b/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/.beacon.toml new file mode 100644 index 0000000..bad8d98 --- /dev/null +++ b/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/.beacon.toml @@ -0,0 +1 @@ +epic = "ux-and-install" diff --git a/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/spec.md b/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/spec.md new file mode 100644 index 0000000..ceb2877 --- /dev/null +++ b/specs/002-manager-compatible-install-requirements-txt-and-custom-node-list-registration/spec.md @@ -0,0 +1,131 @@ +# Feature Specification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` + +**Created**: [DATE] + +**Status**: Draft + +**Input**: User description: "$ARGUMENTS" + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - [Brief Title] (Priority: P1) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 - [Brief Title] (Priority: P2) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 3 - [Brief Title] (Priority: P3) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +[Add more user stories as needed, each with an assigned priority] + +### Edge Cases + + + +- What happens when [boundary condition]? +- How does system handle [error scenario]? + +## Requirements *(mandatory)* + + + +### Functional Requirements + +- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] +- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] +- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] +- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] +- **FR-005**: System MUST [behavior, e.g., "log all security events"] + +*Example of marking unclear requirements:* + +- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] +- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] + +### Key Entities *(include if feature involves data)* + +- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 2]**: [What it represents, relationships to other entities] + +## Success Criteria *(mandatory)* + + + +### Measurable Outcomes + +- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] +- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] + +## Assumptions + + + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] +- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] +- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] diff --git a/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/.beacon.toml b/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/.beacon.toml new file mode 100644 index 0000000..bad8d98 --- /dev/null +++ b/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/.beacon.toml @@ -0,0 +1 @@ +epic = "ux-and-install" diff --git a/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/spec.md b/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/spec.md new file mode 100644 index 0000000..ceb2877 --- /dev/null +++ b/specs/003-formatstring-frontend-ux-debounce-connection-migration-node-id-parity-toast-feedback/spec.md @@ -0,0 +1,131 @@ +# Feature Specification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` + +**Created**: [DATE] + +**Status**: Draft + +**Input**: User description: "$ARGUMENTS" + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - [Brief Title] (Priority: P1) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 - [Brief Title] (Priority: P2) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 3 - [Brief Title] (Priority: P3) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +[Add more user stories as needed, each with an assigned priority] + +### Edge Cases + + + +- What happens when [boundary condition]? +- How does system handle [error scenario]? + +## Requirements *(mandatory)* + + + +### Functional Requirements + +- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] +- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] +- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] +- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] +- **FR-005**: System MUST [behavior, e.g., "log all security events"] + +*Example of marking unclear requirements:* + +- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] +- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] + +### Key Entities *(include if feature involves data)* + +- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 2]**: [What it represents, relationships to other entities] + +## Success Criteria *(mandatory)* + + + +### Measurable Outcomes + +- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] +- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] + +## Assumptions + + + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] +- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] +- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] diff --git a/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/.beacon.toml b/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/.beacon.toml new file mode 100644 index 0000000..bad8d98 --- /dev/null +++ b/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/.beacon.toml @@ -0,0 +1 @@ +epic = "ux-and-install" diff --git a/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/spec.md b/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/spec.md new file mode 100644 index 0000000..ceb2877 --- /dev/null +++ b/specs/004-node-logic-correctness-per-instance-formatstring-schema-randomchoice-determinism-circuitbreaker-any-type/spec.md @@ -0,0 +1,131 @@ +# Feature Specification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` + +**Created**: [DATE] + +**Status**: Draft + +**Input**: User description: "$ARGUMENTS" + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - [Brief Title] (Priority: P1) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 - [Brief Title] (Priority: P2) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 3 - [Brief Title] (Priority: P3) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +[Add more user stories as needed, each with an assigned priority] + +### Edge Cases + + + +- What happens when [boundary condition]? +- How does system handle [error scenario]? + +## Requirements *(mandatory)* + + + +### Functional Requirements + +- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] +- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] +- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] +- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] +- **FR-005**: System MUST [behavior, e.g., "log all security events"] + +*Example of marking unclear requirements:* + +- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] +- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] + +### Key Entities *(include if feature involves data)* + +- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 2]**: [What it represents, relationships to other entities] + +## Success Criteria *(mandatory)* + + + +### Measurable Outcomes + +- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] +- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] + +## Assumptions + + + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] +- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] +- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] diff --git a/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/.beacon.toml b/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/.beacon.toml new file mode 100644 index 0000000..bad8d98 --- /dev/null +++ b/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/.beacon.toml @@ -0,0 +1 @@ +epic = "ux-and-install" diff --git a/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/spec.md b/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/spec.md new file mode 100644 index 0000000..ceb2877 --- /dev/null +++ b/specs/005-metadata-cleanup-pyproject-description-scripts-dead-code-removal-tooltips-category-consistency/spec.md @@ -0,0 +1,131 @@ +# Feature Specification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` + +**Created**: [DATE] + +**Status**: Draft + +**Input**: User description: "$ARGUMENTS" + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - [Brief Title] (Priority: P1) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 - [Brief Title] (Priority: P2) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 3 - [Brief Title] (Priority: P3) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +[Add more user stories as needed, each with an assigned priority] + +### Edge Cases + + + +- What happens when [boundary condition]? +- How does system handle [error scenario]? + +## Requirements *(mandatory)* + + + +### Functional Requirements + +- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] +- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] +- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] +- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] +- **FR-005**: System MUST [behavior, e.g., "log all security events"] + +*Example of marking unclear requirements:* + +- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] +- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] + +### Key Entities *(include if feature involves data)* + +- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 2]**: [What it represents, relationships to other entities] + +## Success Criteria *(mandatory)* + + + +### Measurable Outcomes + +- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] +- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] + +## Assumptions + + + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] +- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] +- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]