@gadicc/loom 1.18.0 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README.md +70 -5
  2. package/THIRD_PARTY_NOTICES.md +11 -10
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +18 -0
  5. package/esm/src/cli/mod.d.ts.map +1 -1
  6. package/esm/src/cli/mod.js +16 -1
  7. package/esm/src/jobs/controller.d.ts +14 -1
  8. package/esm/src/jobs/controller.d.ts.map +1 -1
  9. package/esm/src/jobs/controller.js +54 -3
  10. package/esm/src/jobs/events.d.ts +9 -1
  11. package/esm/src/jobs/events.d.ts.map +1 -1
  12. package/esm/src/jobs/events.js +15 -2
  13. package/esm/src/jobs/mod.d.ts +1 -0
  14. package/esm/src/jobs/mod.d.ts.map +1 -1
  15. package/esm/src/jobs/mod.js +1 -0
  16. package/esm/src/jobs/run.d.ts +20 -1
  17. package/esm/src/jobs/run.d.ts.map +1 -1
  18. package/esm/src/jobs/run.js +29 -4
  19. package/esm/src/jobs/sanitize.d.ts +30 -0
  20. package/esm/src/jobs/sanitize.d.ts.map +1 -0
  21. package/esm/src/jobs/sanitize.js +91 -0
  22. package/esm/src/mail/postal.d.ts.map +1 -1
  23. package/esm/src/mail/postal.js +25 -20
  24. package/esm/src/mail/sender.d.ts +5 -0
  25. package/esm/src/mail/sender.d.ts.map +1 -0
  26. package/esm/src/mail/sender.js +48 -0
  27. package/esm/src/mail/service.d.ts.map +1 -1
  28. package/esm/src/mail/service.js +7 -5
  29. package/esm/src/next/jobs/route.d.ts.map +1 -1
  30. package/esm/src/next/jobs/route.js +1 -1
  31. package/package.json +2 -2
  32. package/script/src/cli/externalSkills.d.ts.map +1 -1
  33. package/script/src/cli/externalSkills.js +18 -0
  34. package/script/src/cli/mod.d.ts.map +1 -1
  35. package/script/src/cli/mod.js +16 -1
  36. package/script/src/jobs/controller.d.ts +14 -1
  37. package/script/src/jobs/controller.d.ts.map +1 -1
  38. package/script/src/jobs/controller.js +54 -3
  39. package/script/src/jobs/events.d.ts +9 -1
  40. package/script/src/jobs/events.d.ts.map +1 -1
  41. package/script/src/jobs/events.js +15 -2
  42. package/script/src/jobs/mod.d.ts +1 -0
  43. package/script/src/jobs/mod.d.ts.map +1 -1
  44. package/script/src/jobs/mod.js +1 -0
  45. package/script/src/jobs/run.d.ts +20 -1
  46. package/script/src/jobs/run.d.ts.map +1 -1
  47. package/script/src/jobs/run.js +29 -4
  48. package/script/src/jobs/sanitize.d.ts +30 -0
  49. package/script/src/jobs/sanitize.d.ts.map +1 -0
  50. package/script/src/jobs/sanitize.js +97 -0
  51. package/script/src/mail/postal.d.ts.map +1 -1
  52. package/script/src/mail/postal.js +25 -20
  53. package/script/src/mail/sender.d.ts +5 -0
  54. package/script/src/mail/sender.d.ts.map +1 -0
  55. package/script/src/mail/sender.js +52 -0
  56. package/script/src/mail/service.d.ts.map +1 -1
  57. package/script/src/mail/service.js +7 -5
  58. package/script/src/next/jobs/route.d.ts.map +1 -1
  59. package/script/src/next/jobs/route.js +1 -1
  60. package/skills/loom/SKILL.md +14 -1
  61. package/skills/loom-jobs/SKILL.md +27 -0
  62. package/skills/loom-mail/SKILL.md +14 -3
  63. package/skills/loom-torvalds-review/SKILL.md +116 -0
  64. package/skills/loom-torvalds-review/agents/openai.yaml +4 -0
  65. package/skills/loom-torvalds-review/references/context-profiles.md +156 -0
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: loom-torvalds-review
3
+ description: Context-aware code and design review for Loom consumer projects, adapting the linus-torvalds-skill reviewer method to the actual runtime and product contract. Use when reviewing a diff or pull request, assessing an API or architecture change, checking a refactor or bug fix, challenging a performance claim, or doing the final engineering review of implementation work, especially in Next.js and other web applications.
4
+ ---
5
+
6
+ # Loom Torvalds Review
7
+
8
+ Apply the useful habits distilled by the upstream
9
+ [`mte90/linus-torvalds-skill`](https://github.com/mte90/linus-torvalds-skill):
10
+ correctness, simple data flow, compatibility, evidence, focused changes, and
11
+ clear technical reasoning. Do not treat Linux kernel implementation details,
12
+ corpus-derived severity rates, or Linus Torvalds's persona as universal rules.
13
+
14
+ ## Establish authority and context
15
+
16
+ 1. Read the repository instructions. In a Loom consumer, use the `loom` skill
17
+ first and read `loom.json`.
18
+ 2. Treat this skill as the context and precedence layer for
19
+ `linus-torvalds-skill`. When the two disagree, follow this skill and the
20
+ repository's explicit contract.
21
+ 3. For a code or design review, read
22
+ `.agents/skills/linus-torvalds-skill/SKILL.md` when it is installed. Treat
23
+ its triggers as a source of review questions, not automatic findings. Do not
24
+ load or imitate an upstream `soul` or persona file.
25
+ 4. If the upstream skill is not installed, continue with this skill. Mention
26
+ `loom add skills` only when the missing deeper review catalog materially
27
+ limits the task.
28
+
29
+ ## Select profiles before reviewing
30
+
31
+ Classify each changed area; a mixed diff may need more than one profile.
32
+
33
+ - Use **web application** by default when `loom.json` identifies Next.js or the
34
+ project uses a browser UI, HTTP handlers, server actions, queues, or a web
35
+ database. This is Loom's normal consumer profile.
36
+ - Use **shared library or CLI** for package exports, command behavior, generated
37
+ output, manifests, and cross-runtime tooling.
38
+ - Use **systems or native** only for native code, FFI, shared-memory workers,
39
+ runtime internals, or other code where memory layout and low-level
40
+ synchronization genuinely govern correctness.
41
+ - Add **prototype** only when the project explicitly identifies the code as
42
+ disposable or exploratory. Never use that label to relax security, privacy,
43
+ authorization, or real-user data integrity.
44
+
45
+ Read [references/context-profiles.md](references/context-profiles.md) for the
46
+ selected profiles and for the list of upstream checks that are disabled unless
47
+ their prerequisites are present.
48
+
49
+ ## Apply Loom's precedence
50
+
51
+ Resolve competing concerns in this order:
52
+
53
+ 1. Security, privacy, authorization, data integrity, and behavioral correctness.
54
+ 2. Explicit product requirements and supported user, API, data, and semver
55
+ contracts.
56
+ 3. Reproducible evidence, operability, reversibility, and failure recovery.
57
+ 4. Simplicity, readable data flow, and maintainability.
58
+ 5. Performance against an explicit budget or realistic measurement.
59
+ 6. Local style and cosmetic consistency.
60
+
61
+ Move performance higher only when the repository defines it as a hard contract
62
+ and the change has relevant evidence. Never rank style, micro-optimization, or
63
+ kernel convention above security or supported users.
64
+
65
+ ## Review the change
66
+
67
+ 1. Establish the requested behavior, changed scope, supported environments,
68
+ public boundaries, and trust boundaries. For a review-only request, inspect
69
+ and report; do not modify the code.
70
+ 2. Trace the data and state transitions before judging local syntax. Include
71
+ client/server boundaries, persistence, retries, caching, and partial failure
72
+ where relevant.
73
+ 3. Apply only upstream triggers whose prerequisites exist in this context.
74
+ Translate the underlying concern into the project's idioms instead of copying
75
+ a kernel remedy.
76
+ 4. Check the actual diff for unrelated churn, compatibility changes, hidden
77
+ costs, unnecessary special cases, inaccurate docs, and missing cleanup
78
+ created by the change.
79
+ 5. Seek proportionate evidence. Reproduce correctness failures; use realistic
80
+ measurements for performance claims; run the repository's relevant tests,
81
+ typecheck, lint, and build when implementation work is in scope.
82
+ 6. Derive severity from concrete impact and reachability. Ignore the upstream
83
+ corpus percentages when deciding whether a finding blocks the change.
84
+
85
+ ## Keep the method humane and practical
86
+
87
+ - Be direct, specific, and technically confident, but do not role-play Linus,
88
+ use profanity, insult people, or manufacture outrage. Critique code and
89
+ decisions, never the author.
90
+ - Prefer a root-cause fix, but allow a contained mitigation, compatibility
91
+ bridge, feature flag, or staged migration when external constraints or an
92
+ incident make that the safer engineering choice. State the residual risk and
93
+ follow-up condition.
94
+ - Do not reject a helper, option object, opaque type, framework abstraction, or
95
+ feature flag by category. Ask whether it makes the common path clearer,
96
+ preserves ownership boundaries, or represents proven variation.
97
+ - Do not import C or kernel conventions into TypeScript APIs. Use the target
98
+ language, framework, deployment platform, and repository conventions.
99
+ - Treat formatter-owned whitespace, contractions, and personal taste as
100
+ non-findings unless they violate an explicit local rule or impair meaning.
101
+
102
+ ## Report findings
103
+
104
+ Lead with actionable findings ordered by impact. For each finding, include:
105
+
106
+ - the smallest useful file and line span;
107
+ - the violated project contract or realistic failure mode;
108
+ - evidence that the behavior is reachable;
109
+ - a concrete direction for correction.
110
+
111
+ Separate blocking defects from suggestions. Do not inflate a speculative concern
112
+ into a finding. If no actionable findings remain, say so and identify any
113
+ material verification gap.
114
+
115
+ The review is complete when every finding is context-valid, evidence-backed, and
116
+ more useful than the kernel-flavored rule that prompted the question.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Torvalds Review for Loom"
3
+ short_description: "Context-aware, evidence-led code review"
4
+ default_prompt: "Use $loom-torvalds-review to review this change with context-appropriate Torvalds-style engineering rigor."
@@ -0,0 +1,156 @@
1
+ # Context profiles
2
+
3
+ Use the sections matching the changed paths. The core question is always the
4
+ same: what real contract or failure mode does this rule protect here?
5
+
6
+ ## Web application profile
7
+
8
+ ### Contracts and compatibility
9
+
10
+ - Treat HTTP shapes, database schemas, stored data, URLs, auth behavior, public
11
+ component/package APIs, and observable UI behavior as possible contracts.
12
+ - Distinguish public behavior from internal implementation. Internal code may
13
+ change freely when callers, persisted data, and user behavior remain intact.
14
+ - Evaluate compatibility through the project's versioning and migration model. A
15
+ coordinated migration or a documented major release is not equivalent to
16
+ silently breaking users.
17
+ - Prefer deprecation or compatibility bridges when they are cheaper and safer,
18
+ but do not preserve a security vulnerability or corrupt data for the sake of
19
+ compatibility.
20
+
21
+ ### Error handling and recovery
22
+
23
+ - Use idiomatic exceptions, typed results, HTTP responses, error boundaries,
24
+ retries, and user-visible recovery. Do not require kernel-style integer error
25
+ codes.
26
+ - A process crash, unhandled rejection, lost mutation, or permanently stuck UI
27
+ may be the web equivalent of an unrecoverable kernel path. An assertion for a
28
+ true programmer invariant can still be appropriate.
29
+ - Review retry and fallback behavior for idempotency, duplicate effects,
30
+ cancellation, timeout, and misleading success states.
31
+
32
+ ### Abstraction and state
33
+
34
+ - Judge components, hooks, services, repositories, adapters, and option objects
35
+ by ownership, reuse, testability, and whether they clarify a client/server or
36
+ provider boundary.
37
+ - Reject speculative layers with no present variation. Keep a small abstraction
38
+ when it prevents duplication, centralizes a contract, or isolates a volatile
39
+ dependency.
40
+ - Prefer data models and state machines that make impossible states difficult to
41
+ represent. Check loading, empty, error, stale, optimistic, and partial states
42
+ where the user can observe them.
43
+
44
+ ### Concurrency and performance
45
+
46
+ - Translate concurrency into async races, database transactions, optimistic
47
+ concurrency, queues, idempotency keys, cache invalidation, and distributed
48
+ coordination. JavaScript's event loop does not remove those races.
49
+ - Apply lock, atomic, memory-ordering, and cache-line advice only to actual
50
+ shared-memory workers, native modules, or runtime internals.
51
+ - Measure what users or operators experience: latency distributions, Core Web
52
+ Vitals when relevant, request/query counts, bundle size, memory, cold starts,
53
+ queue throughput, or provider cost. Do not demand a benchmark for an unclaimed
54
+ and immaterial micro-optimization.
55
+
56
+ ### Web security and usability
57
+
58
+ - Prioritize authentication and authorization separation, tenant isolation,
59
+ injection, XSS, CSRF, SSRF, unsafe redirects, secret exposure, cookie and
60
+ origin policy, cache leakage, upload/download boundaries, and untrusted input.
61
+ - Treat accessibility, destructive-action confirmation, and recoverable user
62
+ flows as correctness when they are part of the product contract.
63
+ - Prefer secure, private defaults. Require an explicit reason before a default
64
+ sends data externally, weakens access control, or exposes internal details.
65
+
66
+ ### Testing and style
67
+
68
+ - Test the affected support matrix, not every browser and platform in existence.
69
+ Add production builds for framework, bundler, server/client-boundary, or
70
+ deployment-sensitive changes.
71
+ - Let the project formatter, linter, typechecker, and design system define
72
+ style. Whitespace and wording are findings only when they obscure meaning or
73
+ violate that contract.
74
+
75
+ ## Shared library or CLI profile
76
+
77
+ - Treat exported types and functions, command flags, exit status, stdout/stderr,
78
+ generated files, config schemas, and documented runtime support as contracts.
79
+ - Preserve semver. Breaking changes are acceptable only through the repository's
80
+ declared release and migration path; additive compatibility is preferred.
81
+ - Use idiomatic errors for each runtime. Stable CLI exit codes and parseable
82
+ output matter, but a library does not need C's `0`/negative-error convention.
83
+ - Prefer portable Web APIs in Deno-first shared code when they meet the need.
84
+ Isolate unavoidable Node or native behavior and test the supported runtimes.
85
+ - Apply bisectability to the commits that will be shipped. A working tree need
86
+ not be valid at every keystroke, while each final commit should build and make
87
+ coherent sense when the repository requires that history quality.
88
+ - Require benchmarks only for performance claims or budgets that affect package
89
+ users. Include startup time, artifact size, throughput, memory, and generated
90
+ client-bundle impact when relevant.
91
+
92
+ ## Systems or native profile
93
+
94
+ - Apply upstream memory-layout, lifetime, synchronization, atomics, executable
95
+ memory, ABI, and architecture advice when the implementation actually exposes
96
+ those concerns.
97
+ - Keep Loom's precedence and tone rules. Security and supported contracts still
98
+ outrank an unmeasured micro-optimization, and corpus percentages still do not
99
+ determine severity.
100
+ - Translate Linux-specific APIs to the target operating system and runtime.
101
+ `sysctl`, `seq_printf`, `READ_ONCE`, BKL, `execve`, and errno examples are
102
+ evidence for a principle, not portable remedies.
103
+
104
+ ## Prototype modifier
105
+
106
+ - Relax long-term compatibility, exhaustive testing, and abstraction longevity
107
+ only when the prototype boundary is explicit and the code is not silently
108
+ becoming production infrastructure.
109
+ - Keep cheap diagnostics and a clear path to delete or replace the experiment.
110
+ - Do not relax security, privacy, authorization, billing integrity, or real-user
111
+ data protection merely because the feature is experimental.
112
+
113
+ ## Upstream checks disabled by default
114
+
115
+ Do not report these as findings unless the stated prerequisite exists:
116
+
117
+ | Upstream check | Prerequisite or contextual translation |
118
+ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
119
+ | Return `0` or a negative error; never return byte counts | A C/ABI contract that defines those exact semantics. Use idiomatic typed errors elsewhere. |
120
+ | A write returning `0` means disk full | A write-like API whose documented contract gives zero that meaning. |
121
+ | Double underscores imply an internal-only symbol | A language or repository convention that explicitly assigns that meaning. |
122
+ | Opaque types are harmful | Callers genuinely require layout access. In most app and library APIs, encapsulation may be beneficial. |
123
+ | A new flag or option is inherently worse than an error | Compare clarity, compatibility, state-space growth, and target-language idiom. Feature flags can also support safe rollout. |
124
+ | A helper around one line is needless | The helper adds no domain name, policy, reuse, test seam, or ownership boundary. |
125
+ | A lock around one primitive must become an atomic | Shared-memory concurrency exists and the replacement preserves all ordering and compound invariants. |
126
+ | `READ_ONCE`, acquire/release, BKL, or tail-call/cache rules | Low-level memory ordering or instruction-cache behavior exists and is relevant on the target runtime. |
127
+ | Escaped stack pointers, executable pages, or per-CPU stack limits | Native/FFI/runtime code exposes manual lifetime, executable memory, or constrained stacks. |
128
+ | Hardware opt-in, sysctl, vsyscall, `seq_printf`, or `execve` advice | An equivalent platform capability exists. Preserve the principle, not the Linux mechanism. |
129
+ | RSA is categorically obsolete or post-quantum wording decides safety | Current project policy and authoritative cryptographic guidance establish the actual threat and migration requirement. |
130
+ | Contractions, blank lines, or nonstandard extensions are defects | Local style, parser, portability target, or readability provides a concrete reason. |
131
+ | Every low-level change needs every-platform testing | The affected supported environments require it. Test the real support matrix proportionately. |
132
+ | One-line commit header, blank line, then body is universal | The repository's commit and release tooling requires that shape. |
133
+ | Corpus reject/request-change percentages set severity | Never. Severity comes from current impact, likelihood, reachability, and recovery cost. |
134
+
135
+ ## Translation examples
136
+
137
+ | Upstream principle | Web or package translation |
138
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
139
+ | Do not break userspace | Preserve documented API/UI/data behavior or provide a semver and migration path. |
140
+ | Fix the data structure | Simplify the schema, state model, discriminated union, or ownership boundary before adding branches. |
141
+ | Do not crash for a recoverable error | Return a useful response, preserve user work, expose retry/recovery, and log enough to diagnose. |
142
+ | Show macro-benchmarks | Measure representative user journeys, server latency, queries, bundles, queues, or cost. |
143
+ | Avoid hidden-cost abstractions | Make network, database, rendering, serialization, and provider calls visible in naming and boundaries. |
144
+ | Keep patches bisectable | Produce coherent, buildable commits when commit history is part of the requested deliverable. |
145
+
146
+ ## Root cause versus containment
147
+
148
+ Prefer the root cause when it is known and safely fixable. Accept containment
149
+ when it is the safer immediate move, including incident mitigation, upstream
150
+ provider defects, compatibility windows, risky data migrations, or phased
151
+ rollouts. A containment change should identify:
152
+
153
+ 1. the failure it prevents;
154
+ 2. why the root cause cannot be fixed safely in the same change;
155
+ 3. its observability and rollback path;
156
+ 4. the condition for removing or replacing it.