@gadicc/loom 1.17.0 → 1.19.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 (70) hide show
  1. package/README.md +120 -43
  2. package/deno.json +3 -0
  3. package/esm/src/cli/mod.d.ts +3 -1
  4. package/esm/src/cli/mod.d.ts.map +1 -1
  5. package/esm/src/cli/mod.js +968 -342
  6. package/esm/src/cli/projectTooling.d.ts +138 -0
  7. package/esm/src/cli/projectTooling.d.ts.map +1 -0
  8. package/esm/src/cli/projectTooling.js +614 -0
  9. package/esm/src/jobs/controller.d.ts +14 -1
  10. package/esm/src/jobs/controller.d.ts.map +1 -1
  11. package/esm/src/jobs/controller.js +54 -3
  12. package/esm/src/jobs/events.d.ts +9 -1
  13. package/esm/src/jobs/events.d.ts.map +1 -1
  14. package/esm/src/jobs/events.js +15 -2
  15. package/esm/src/jobs/mod.d.ts +1 -0
  16. package/esm/src/jobs/mod.d.ts.map +1 -1
  17. package/esm/src/jobs/mod.js +1 -0
  18. package/esm/src/jobs/run.d.ts +20 -1
  19. package/esm/src/jobs/run.d.ts.map +1 -1
  20. package/esm/src/jobs/run.js +29 -4
  21. package/esm/src/jobs/sanitize.d.ts +30 -0
  22. package/esm/src/jobs/sanitize.d.ts.map +1 -0
  23. package/esm/src/jobs/sanitize.js +91 -0
  24. package/esm/src/mail/postal.d.ts.map +1 -1
  25. package/esm/src/mail/postal.js +25 -20
  26. package/esm/src/mail/sender.d.ts +5 -0
  27. package/esm/src/mail/sender.d.ts.map +1 -0
  28. package/esm/src/mail/sender.js +48 -0
  29. package/esm/src/mail/service.d.ts.map +1 -1
  30. package/esm/src/mail/service.js +7 -5
  31. package/esm/src/next/jobs/route.d.ts.map +1 -1
  32. package/esm/src/next/jobs/route.js +1 -1
  33. package/package.json +3 -2
  34. package/script/src/cli/mod.d.ts +3 -1
  35. package/script/src/cli/mod.d.ts.map +1 -1
  36. package/script/src/cli/mod.js +968 -342
  37. package/script/src/cli/projectTooling.d.ts +138 -0
  38. package/script/src/cli/projectTooling.d.ts.map +1 -0
  39. package/script/src/cli/projectTooling.js +634 -0
  40. package/script/src/jobs/controller.d.ts +14 -1
  41. package/script/src/jobs/controller.d.ts.map +1 -1
  42. package/script/src/jobs/controller.js +54 -3
  43. package/script/src/jobs/events.d.ts +9 -1
  44. package/script/src/jobs/events.d.ts.map +1 -1
  45. package/script/src/jobs/events.js +15 -2
  46. package/script/src/jobs/mod.d.ts +1 -0
  47. package/script/src/jobs/mod.d.ts.map +1 -1
  48. package/script/src/jobs/mod.js +1 -0
  49. package/script/src/jobs/run.d.ts +20 -1
  50. package/script/src/jobs/run.d.ts.map +1 -1
  51. package/script/src/jobs/run.js +29 -4
  52. package/script/src/jobs/sanitize.d.ts +30 -0
  53. package/script/src/jobs/sanitize.d.ts.map +1 -0
  54. package/script/src/jobs/sanitize.js +97 -0
  55. package/script/src/mail/postal.d.ts.map +1 -1
  56. package/script/src/mail/postal.js +25 -20
  57. package/script/src/mail/sender.d.ts +5 -0
  58. package/script/src/mail/sender.d.ts.map +1 -0
  59. package/script/src/mail/sender.js +52 -0
  60. package/script/src/mail/service.d.ts.map +1 -1
  61. package/script/src/mail/service.js +7 -5
  62. package/script/src/next/jobs/route.d.ts.map +1 -1
  63. package/script/src/next/jobs/route.js +1 -1
  64. package/skills/loom/SKILL.md +38 -23
  65. package/skills/loom-db/SKILL.md +9 -7
  66. package/skills/loom-db/references/db-stack.md +2 -1
  67. package/skills/loom-jobs/SKILL.md +36 -6
  68. package/skills/loom-lingui/SKILL.md +38 -0
  69. package/skills/loom-lingui/agents/openai.yaml +4 -0
  70. package/skills/loom-mail/SKILL.md +14 -3
@@ -15,10 +15,13 @@ project.
15
15
  ## Start here
16
16
 
17
17
  1. Read `loom.json` first.
18
- 2. Identify which loom features are active and which paths are configured there.
19
- 3. Treat the active loom features as the contract between the app and the shared
18
+ 2. Read `project.tooling` and use its recorded task runner/config and dependency
19
+ manager/config. Do not infer them again from whichever config you notice
20
+ first.
21
+ 3. Identify which loom features are active and which paths are configured there.
22
+ 4. Treat the active loom features as the contract between the app and the shared
20
23
  package.
21
- 4. Run `loom status` when you need a quick summary of active features, local
24
+ 5. Run `loom status` when you need a quick summary of active features, local
22
25
  Loom dev state, or managed/recommended skill links.
23
26
 
24
27
  ## Cross-repository Loom work
@@ -45,6 +48,12 @@ from the consumer's working directory.
45
48
  instead of duplicating it in one app.
46
49
  - Do not assume one file layout. Respect `app/...` vs `src/app/...` and any
47
50
  configured loom paths.
51
+ - Do not assume commands live in `package.json` or run with pnpm. Projects may
52
+ use `deno.json`/`deno.jsonc`, package scripts, or package dependencies with
53
+ canonical Deno tasks.
54
+ - Preserve JSONC comments, unrelated tasks, and complex existing build commands.
55
+ Use Loom's project-tooling task helpers for shared CLI work instead of direct
56
+ whole-file rewrites or string-only runner guesses.
48
57
  - If a loom-managed file exists only as a thin wrapper, keep it thin unless the
49
58
  app intentionally needs custom behavior there.
50
59
 
@@ -52,9 +61,9 @@ from the consumer's working directory.
52
61
 
53
62
  - Next commands such as `next dev`, `next build`, and server runtime code load
54
63
  `.env*` files themselves. Do not add extra env loading around those paths.
55
- - Non-Next commands that need app env should run through a project package
56
- script that centralizes env loading, or directly through
57
- `pnpm exec loom env -- <command>`.
64
+ - Non-Next commands that need app env should run through the authoritative
65
+ project task that centralizes env loading, or directly through the installed
66
+ `loom env -- <command>` command.
58
67
  - `loom env -- <command> [...args]` loads env files from the consumer project
59
68
  root with Next-compatible `@next/env` semantics, preserves existing shell env
60
69
  precedence, then runs the command from the project root.
@@ -147,33 +156,36 @@ as more authoritative than a generic mapped error when deciding what failed.
147
156
 
148
157
  ## Local development
149
158
 
150
- - For local unpublished Loom package development in pnpm apps, prefer
151
- `loom dev local <path>` over `pnpm link`.
152
- - The managed local-dev flow keeps the committed dependency on the published
153
- Loom version, writes a managed `file:` marker in `pnpm-workspace.yaml`, and
154
- then requires the explicit `pnpm update --no-save` command that
155
- `loom dev local` prints for the direct dependency.
159
+ - For local unpublished Loom package development, use `loom dev local <path>`.
160
+ Loom uses a managed `file:` override in `pnpm-workspace.yaml` for pnpm
161
+ projects and a local `links` entry in the authoritative Deno config for Deno
162
+ projects.
163
+ - The managed flow keeps the committed dependency/import on a published Loom
164
+ version. Use the printed pnpm refresh command or `deno install`, according to
165
+ `project.tooling`.
156
166
  - This still avoids the peer-resolution problems we observed with `pnpm link`
157
167
  when Loom is consumed by React apps.
158
168
  - Treat this as a workaround for current pnpm behavior, not a permanent
159
169
  preference. If pnpm's local-link behavior changes enough to preserve peer
160
170
  resolution cleanly for Loom, this workaround can be revisited or removed.
161
171
  - Before committing app changes or preparing a published build, switch back with
162
- `loom dev published`, then run the published `pnpm update --no-save` command
163
- it prints, and then `pnpm install`.
164
- - `loom dev sync` records the Loom source commit in the managed
165
- `pnpm-workspace.yaml` block and gitignored `.loom/dev-state.json` when the
166
- local package path points at a Loom git checkout.
172
+ `loom dev published`, then run the printed pnpm refresh command or
173
+ `deno install`.
174
+ - `loom dev sync` records the Loom source commit in the managed pnpm block when
175
+ applicable and gitignored `.loom/dev-state.json` for both project kinds when
176
+ the local package path points at a Loom git checkout.
167
177
  - `loom dev published` uses that recorded commit as a release gate when present:
168
178
  the commit must be cleanly synced, reachable from `origin/main`, and either
169
179
  included in a semver release tag or package-equivalent to the latest semver
170
180
  release because only non-package files changed after that tag. The app then
171
181
  switches to the exact published Loom version that covers the sync.
172
- - `loom dev published` also notices stale `pnpm-lock.yaml` resolutions that
173
- still point at local Loom after the workspace override has been removed.
174
- - `loom check` should warn during normal development if `pnpm-lock.yaml` still
175
- resolves Loom locally, if the synced Loom commit is unpublished, or if it is
176
- covered by a newer exact version than the app currently pins.
182
+ - `loom dev published` also removes Deno links and notices stale
183
+ `pnpm-lock.yaml` resolutions that still point at local Loom after a pnpm
184
+ workspace override has been removed.
185
+ - `loom check` should warn during normal development if a Deno link or pnpm
186
+ lockfile still resolves Loom locally, if the synced Loom commit is
187
+ unpublished, or if it is covered by a newer exact version than the app
188
+ currently pins.
177
189
  - If an older local-dev block has no recorded commit, switch back carefully and
178
190
  run `loom dev sync` first whenever the app may depend on unpublished Loom
179
191
  changes.
@@ -200,7 +212,10 @@ as more authoritative than a generic mapped error when deciding what failed.
200
212
 
201
213
  ## Commits
202
214
 
203
- - Use conventional commits with scopes for title.
215
+ - Use conventional commits with scopes for the title. Limit the subject line to
216
+ 50 characters, capitalize the first letter, do not end the subject line with a
217
+ period, use imperative mood (for example, `fix` instead of `fixed` or
218
+ `fixes`), and wrap the body at 72 characters.
204
219
  - In the body, include the motivation, summary of changes, and anything else of
205
220
  note.
206
221
  - At bottom: "Co-authored with <Assistant> (<model>, reasoning <level>)"
@@ -10,9 +10,12 @@ Use this skill when working on the shared DB stack from a consuming app.
10
10
  ## Start here
11
11
 
12
12
  1. Read `loom.json`.
13
- 2. Inspect `features.db.config` and use the configured module and directory
13
+ 2. Read `project.tooling` and use its authoritative task/dependency configs and
14
+ runners; DB tasks may live in `deno.json(c)` even when npm dependencies live
15
+ in `package.json`.
16
+ 3. Inspect `features.db.config` and use the configured module and directory
14
17
  paths instead of assuming defaults.
15
- 3. Check the app-local schema barrel before changing any Loom-managed DB files.
18
+ 4. Check the app-local schema barrel before changing any Loom-managed DB files.
16
19
 
17
20
  ## Ownership boundaries
18
21
 
@@ -25,10 +28,9 @@ Use this skill when working on the shared DB stack from a consuming app.
25
28
  shared PGlite test harness.
26
29
  - Valibot generated files stay app-local, but should be regenerated through
27
30
  `loom db schema-gen` instead of ad hoc commands.
28
- - DB-backed scripts, Drizzle commands, direct SQL inspection, and migrations
29
- should use the app's env-aware package scripts or
30
- `pnpm exec loom env -- <command>`. Do not add `dotenv` or `@next/env` imports
31
- to implementation files.
31
+ - DB-backed tasks, Drizzle commands, direct SQL inspection, and migrations
32
+ should use the app's authoritative env-aware tasks or `loom env -- <command>`.
33
+ Do not add `dotenv` or `@next/env` imports to implementation files.
32
34
  - `createDrizzleConfig()` prefers `MIGRATION_DATABASE_URL_UNPOOLED`, then
33
35
  `MIGRATION_DATABASE_URL`, before the gradual-adoption fallbacks
34
36
  `DATABASE_URL_UNPOOLED` and `DATABASE_URL`.
@@ -60,7 +62,7 @@ Use this skill when working on the shared DB stack from a consuming app.
60
62
  ## Verification
61
63
 
62
64
  - Run `loom check` after DB feature changes.
63
- - Confirm package scripts still point at Loom-managed commands, especially
65
+ - Confirm authoritative tasks still point at Loom-managed commands, especially
64
66
  `schema:gen`, `db:fixtures`, and the Drizzle script that runs through
65
67
  `loom env --`.
66
68
  - Confirm `drizzle.config.ts` still points at the configured schema and drizzle
@@ -9,7 +9,8 @@ The Loom DB feature standardizes the cross-app wiring around:
9
9
  - thin wrappers for `tests/memory-pglite.ts`
10
10
  - thin wrappers for `src/db/valibot/refinements/_common.ts`
11
11
  - `src/db/valibot/index.ts`
12
- - `package.json` DB scripts, including `schema:gen` and `db:fixtures`
12
+ - authoritative DB tasks in `package.json` or `deno.json(c)`, including
13
+ `schema:gen` and `db:fixtures`
13
14
 
14
15
  It does not own:
15
16
 
@@ -10,9 +10,11 @@ Use this skill when working on the shared jobs feature from a consuming app.
10
10
  ## Start here
11
11
 
12
12
  1. Read `loom.json`.
13
- 2. Inspect `features.jobs.config` and use the configured module and UI paths
13
+ 2. Read `project.tooling`; the `job` task may be a Deno task even when
14
+ dependencies are managed through `package.json`.
15
+ 3. Inspect `features.jobs.config` and use the configured module and UI paths
14
16
  instead of assuming defaults.
15
- 3. Check the app-local jobs catalog files before changing wrappers.
17
+ 4. Check the app-local jobs catalog files before changing wrappers.
16
18
 
17
19
  ## Ownership boundaries
18
20
 
@@ -33,8 +35,8 @@ Use this skill when working on the shared jobs feature from a consuming app.
33
35
  - The configured catalog imports, especially metadata-only exports used by the
34
36
  jobs list page.
35
37
  - Direct-runner settings and script paths when the app has opted into them.
36
- - Direct job runners should assume env has already been loaded by the package
37
- script. Keep env loading in scripts such as `job` via `loom env --`, not in
38
+ - Direct job runners should assume env has already been loaded by the project
39
+ task. Keep env loading in tasks such as `job` via `loom env --`, not in
38
40
  `scripts/jobDirect.ts`.
39
41
 
40
42
  ## Catalog runtime boundaries
@@ -97,6 +99,33 @@ Use this skill when working on the shared jobs feature from a consuming app.
97
99
  - If the app has no always-on worker in the current environment, call out the
98
100
  manual runner or admin route needed to drain queued work.
99
101
 
102
+ ## Output sanitation and error disclosure
103
+
104
+ - Use `createJobOutputRedactor()` and pass the result as `outputSanitizer` on
105
+ the execution, response, or route-handler options. Do not implement redaction
106
+ only inside a text or HTML formatter; controller-level sanitation is what also
107
+ covers NDJSON, direct runners, HTTP output, and custom formatters.
108
+ - Redaction maps are ordered. Each exact-string or RegExp rule sees the prior
109
+ rule's result. Exact strings match every occurrence; RegExp rules replace
110
+ every match independent of `g`, `y`, or `lastIndex`. `true` means
111
+ `[REDACTED]`, and string replacements are literal rather than replacement
112
+ templates.
113
+ - Never add an empty exact-string rule. Loom rejects it without including
114
+ configured match or replacement values in the error.
115
+ - The policy recursively sanitizes string values from every controller log level
116
+ and `job.json()` without mutating caller-owned values. Sanitation failure
117
+ emits only the fixed `Job output sanitation failed.` event.
118
+ - Keep expected output, unexpected handler errors, and deferred-task errors as
119
+ distinct decisions. `handlerErrorMessage` opts into a generic literal while
120
+ omission preserves the legacy full stack. Use `deferredTaskErrorHandler`
121
+ separately and use `runDeferredTasksWithResult()` when a failure count affects
122
+ job or audit status; `runDeferredTasks()` keeps its legacy void result.
123
+ - Use `cancellationMessage: false` only when an app intentionally needs silent
124
+ cancellation while retaining the controller's cancellation flag.
125
+ - The boundary covers Loom job-event output, not `console.*`, provider logs,
126
+ audit metadata, URLs, thrown values retained in `execution.result`, external
127
+ log sinks, or object property names.
128
+
100
129
  ## Job Parameters and Validation
101
130
 
102
131
  Loom supports declarative job parameter definitions on each job's `meta` object.
@@ -144,5 +173,6 @@ When adding or upgrading a job:
144
173
  `createJobsRunPage`, and `createJobsRouteHandler`.
145
174
  - Confirm executable catalog entries use `createLazyJob` and the metadata
146
175
  catalog does not import job implementations.
147
- - Confirm the `job` package script runs the direct runner through `loom env --`
148
- and that the direct-runner file does not import `dotenv` or `@next/env`.
176
+ - Confirm the authoritative `job` task runs the direct runner through
177
+ `loom env --` and that the direct-runner file does not import `dotenv` or
178
+ `@next/env`.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: loom-lingui
3
+ description: Manage Lingui catalog tooling in Loom consumer projects. Use when adding, migrating, reviewing, or repairing Lingui dependencies, catalog modes, extraction and compilation tasks, generated-catalog ignores, or Next.js loader and SWC wiring.
4
+ ---
5
+
6
+ # Loom Lingui
7
+
8
+ Treat `.po` catalogs as the reviewable translation source. Do not hand-edit
9
+ generated JavaScript catalogs.
10
+
11
+ ## Workflow
12
+
13
+ 1. Inspect `loom.json`, the Lingui config, dependency and task config,
14
+ `.gitignore`, Next config, and runtime catalog imports.
15
+ 2. Run `loom add lingui` to adopt or repair the managed baseline.
16
+ 3. Confirm the recorded catalog mode matches runtime imports:
17
+ - Use `precompile` when runtime code imports generated `.js` catalogs. Ensure
18
+ the compile task runs before the framework build.
19
+ - Use `loader` when runtime code imports `.po` catalogs. Ensure
20
+ `@lingui/loader` is configured for both Turbopack and webpack when both are
21
+ supported.
22
+ 4. Keep generated catalog patterns ignored. If generated files are already
23
+ tracked, propose removing only those files from the Git index while leaving
24
+ local build output intact.
25
+ 5. Run `loom check`, the Lingui compile task, and the production build.
26
+
27
+ ## Boundaries
28
+
29
+ Leave locale lists, routing, translated content, message IDs, fallback behavior,
30
+ and automated translation providers app-owned. Change them only when the user
31
+ explicitly requests it.
32
+
33
+ Preserve existing Lingui config and custom tasks when Loom reports a conflict.
34
+ Diagnose the mismatch instead of overwriting app-owned behavior.
35
+
36
+ Prefer current package-specific macro entrypoints such as `@lingui/react/macro`
37
+ and `@lingui/core/macro`. Treat mismatched legacy `@lingui/macro` versions as
38
+ migration work, not generated-catalog policy.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Loom Lingui"
3
+ short_description: "Manage Lingui catalogs with Loom"
4
+ default_prompt: "Use $loom-lingui to add or verify Lingui catalog tooling in this project."
@@ -26,9 +26,18 @@ contract.
26
26
  2. Run `loom add mail`.
27
27
  3. Review the materialized schema and generate the app-local migration.
28
28
  4. Replace the generated deny-all access function with the app's admin check.
29
- 5. Configure `POSTAL_API_KEY`, `POSTAL_HOST`, `POSTAL_FROM_EMAIL`, and
30
- `POSTAL_WEBHOOK_PUBLIC_KEYS`. The last value is a JSON array of RSA public
31
- JWKs with `kid`; it is not a shared secret.
29
+ 5. Configure `POSTAL_API_KEY`, `POSTAL_HOST`, `POSTAL_FROM_EMAIL`, optional
30
+ `POSTAL_FROM_NAME`, and `POSTAL_WEBHOOK_PUBLIC_KEYS`. Keep the sender values
31
+ structured:
32
+
33
+ ```dotenv
34
+ POSTAL_FROM_EMAIL=noreply@example.com
35
+ POSTAL_FROM_NAME=Example App
36
+ ```
37
+
38
+ `POSTAL_FROM_EMAIL` must be a bare address, never `Name <address>`.
39
+ `POSTAL_FROM_NAME` is optional. The webhook value is a JSON array of RSA
40
+ public JWKs with `kid`; it is not a shared secret.
32
41
  6. If jobs is active, register the generated `mail-drain` module in the app's
33
42
  full and metadata catalogs and choose an app-owned schedule.
34
43
  7. Configure Postal to POST signed events to the generated webhook route.
@@ -47,6 +56,8 @@ contract.
47
56
  supports an idempotency key.
48
57
  - Bound attachment size at the app/action boundary and never log attachment
49
58
  bodies, API keys, or webhook key material.
59
+ - Keep purpose-specific sender selection in the consumer. Use per-message
60
+ `fromEmail` and `fromName` overrides instead of adding domain policy to Loom.
50
61
 
51
62
  ## Testing
52
63