@rmrdeveloper/sideroom-pi 8.13.0 → 9.0.0

package/skills/sideroom-guidelines/references/languages/javascript.md

@@ -25,6 +25,7 @@ Rules every JavaScript change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -377,11 +378,43 @@ counter++;
 setInterval(checkPaymentStatus, 5_000);
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```js
+// bad
+function createPackingSlip(items, destination) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { destination, totals: { unitCount, weightGrams } };
+}
+// good
+function createPackingSlip(items, destination) {
+  return { destination, totals: calculatePackingTotals(items) };
+}
+
+function calculatePackingTotals(items) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { unitCount, weightGrams };
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.
 
 ## Language-specific conventions
 

package/skills/sideroom-guidelines/references/languages/php-laravel.md

@@ -25,6 +25,7 @@ Rules every PHP or Laravel change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -241,8 +242,40 @@ RULE: Comment only non-obvious intent — a trade-off, a constraint, a hazard na
 Schedule::call($checkPaymentStatus)->everyFiveSeconds();
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```php
+// bad
+function createPackingSlip(array $items, string $destination): PackingSlip {
+    $unitCount = 0;
+    $weightGrams = 0;
+    foreach ($items as $item) {
+        $unitCount += $item->quantity;
+        $weightGrams += $item->quantity * $item->unitWeightGrams;
+    }
+    return new PackingSlip($destination, new PackingTotals($unitCount, $weightGrams));
+}
+// good
+function createPackingSlip(array $items, string $destination): PackingSlip {
+    return new PackingSlip($destination, calculatePackingTotals($items));
+}
+
+function calculatePackingTotals(array $items): PackingTotals {
+    $unitCount = 0;
+    $weightGrams = 0;
+    foreach ($items as $item) {
+        $unitCount += $item->quantity;
+        $weightGrams += $item->quantity * $item->unitWeightGrams;
+    }
+    return new PackingTotals($unitCount, $weightGrams);
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by PHP/Laravel formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by PHP/Laravel formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.

package/skills/sideroom-guidelines/references/languages/python.md

@@ -25,6 +25,7 @@ Rules every Python change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -314,8 +315,36 @@ counter += 1
 scheduler.every(5).seconds.do(check_payment_status)
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```python
+# bad
+def create_packing_slip(items, destination):
+    unit_count = 0
+    weight_grams = 0
+    for item in items:
+        unit_count += item.quantity
+        weight_grams += item.quantity * item.unit_weight_grams
+    return PackingSlip(destination, PackingTotals(unit_count, weight_grams))
+
+# good
+def create_packing_slip(items, destination):
+    return PackingSlip(destination, calculate_packing_totals(items))
+
+def calculate_packing_totals(items) -> PackingTotals:
+    unit_count = 0
+    weight_grams = 0
+    for item in items:
+        unit_count += item.quantity
+        weight_grams += item.quantity * item.unit_weight_grams
+    return PackingTotals(unit_count, weight_grams)
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by Python formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by Python formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.

package/skills/sideroom-guidelines/references/languages/rust.md

@@ -25,6 +25,7 @@ Rules every Rust change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -244,8 +245,40 @@ counter += 1;
 schedule_poll(Duration::from_secs(5));
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```rust
+// bad
+fn create_packing_slip(items: &[PackingItem], destination: String) -> PackingSlip {
+    let mut unit_count = 0;
+    let mut weight_grams = 0;
+    for item in items {
+        unit_count += item.quantity;
+        weight_grams += item.quantity * item.unit_weight_grams;
+    }
+    PackingSlip { destination, totals: PackingTotals { unit_count, weight_grams } }
+}
+// good
+fn create_packing_slip(items: &[PackingItem], destination: String) -> PackingSlip {
+    PackingSlip { destination, totals: calculate_packing_totals(items) }
+}
+
+fn calculate_packing_totals(items: &[PackingItem]) -> PackingTotals {
+    let mut unit_count = 0;
+    let mut weight_grams = 0;
+    for item in items {
+        unit_count += item.quantity;
+        weight_grams += item.quantity * item.unit_weight_grams;
+    }
+    PackingTotals { unit_count, weight_grams }
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by Rust formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by Rust formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.

package/skills/sideroom-guidelines/references/languages/typescript.md

@@ -25,6 +25,7 @@ Rules every TypeScript change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -242,11 +243,47 @@ counter++;
 setInterval(checkPaymentStatus, 5_000);
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```ts
+type PackingItem = { quantity: number; unitWeightGrams: number };
+type PackingTotals = { unitCount: number; weightGrams: number };
+type PackingSlip = { destination: string; totals: PackingTotals };
+
+// bad
+function createPackingSlip(items: readonly PackingItem[], destination: string): PackingSlip {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { destination, totals: { unitCount, weightGrams } };
+}
+// good
+function createPackingSlip(items: readonly PackingItem[], destination: string): PackingSlip {
+  return { destination, totals: calculatePackingTotals(items) };
+}
+
+function calculatePackingTotals(items: readonly PackingItem[]): PackingTotals {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { unitCount, weightGrams };
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by TypeScript formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by TypeScript formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.
 
 ## Language-specific conventions
 

package/skills/sideroom-visual-setup/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sideroom-visual-setup
+description: "Enable, review, or troubleshoot precise Sideroom visual context in a web project, including child projects and development servers in Docker. Use for requests such as 'Activa el contexto visual preciso'; not for ordinary UI changes or browser automation."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Visual context setup
+
+Configure one requested project so a browser selection carries a compiler location
+that Pi can validate against local source. Requires `sideroom_visual_setup`; if
+it is unavailable, load the Sideroom installation that provides it before proceeding.
+
+## Workflow
+
+1. Resolve the requested project relative to Pi's working directory; use `discover`
+   when the target is unknown. Reuse an explicit choice; ask only if it is ambiguous. Read its
+   build config, manifest, lockfile ownership and actual development launch command.
+   Inspect Docker configuration only when it runs the development server.
+2. For a new integration, use `prepare` and apply its edit and installation command
+   through normal Pi tools. The plan owns compiler code, dependency versions and
+   check scripts: do not duplicate that template here or in a helper file. For an
+   existing/custom integration, preserve it and change only what inspection shows
+   is missing. Keep metadata before framework transforms, development-only, with
+   no second browser UI or editor-launch service. Install in the selected workspace
+   and ensure the dependency is also present in the runtime that serves the app.
+3. Check path portability before starting the server:
+   - When runtime and Pi share paths, retain the plan's absolute paths.
+   - When Docker or another runtime has different paths, emit paths relative to the
+     app root and `bind` the actual page origin to that local project, or associate
+     it through F7. Do not bind it to the parent folder merely because Pi runs there.
+     With Code Inspector 2.0.9, `transformCode` checks that `filePath` exists before
+     transforming: a relative input must resolve from the runtime's working
+     directory. Romax's pattern works because its Docker working directory equals
+     Vite's app root. Verify this condition instead of copying it to every project.
+     Reject out-of-project references; do not relax Sideroom's path guards.
+4. Run the project's existing checks, restart the selected development service
+   through its established workflow, and refresh the page. Reload Pi and the
+   companion together if their visual protocols differ; preserve pairing.
+   Select a native element and verify its marker resolves to the intended local
+   file, line and column with **compiler location checked** in F7. If practical,
+   confirm a production build omits markers. A successful install or build alone
+   does not verify browser-to-source resolution.
+
+Report the project, changed files, checks and browser verification status. When
+browser/runtime access is unavailable, finish the configuration and identify the
+remaining verification step; do not label inferred or untested locations exact.