@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.
- package/README.md +120 -43
- package/deno.json +3 -0
- package/esm/src/cli/mod.d.ts +3 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +968 -342
- package/esm/src/cli/projectTooling.d.ts +138 -0
- package/esm/src/cli/projectTooling.d.ts.map +1 -0
- package/esm/src/cli/projectTooling.js +614 -0
- package/esm/src/jobs/controller.d.ts +14 -1
- package/esm/src/jobs/controller.d.ts.map +1 -1
- package/esm/src/jobs/controller.js +54 -3
- package/esm/src/jobs/events.d.ts +9 -1
- package/esm/src/jobs/events.d.ts.map +1 -1
- package/esm/src/jobs/events.js +15 -2
- package/esm/src/jobs/mod.d.ts +1 -0
- package/esm/src/jobs/mod.d.ts.map +1 -1
- package/esm/src/jobs/mod.js +1 -0
- package/esm/src/jobs/run.d.ts +20 -1
- package/esm/src/jobs/run.d.ts.map +1 -1
- package/esm/src/jobs/run.js +29 -4
- package/esm/src/jobs/sanitize.d.ts +30 -0
- package/esm/src/jobs/sanitize.d.ts.map +1 -0
- package/esm/src/jobs/sanitize.js +91 -0
- package/esm/src/mail/postal.d.ts.map +1 -1
- package/esm/src/mail/postal.js +25 -20
- package/esm/src/mail/sender.d.ts +5 -0
- package/esm/src/mail/sender.d.ts.map +1 -0
- package/esm/src/mail/sender.js +48 -0
- package/esm/src/mail/service.d.ts.map +1 -1
- package/esm/src/mail/service.js +7 -5
- package/esm/src/next/jobs/route.d.ts.map +1 -1
- package/esm/src/next/jobs/route.js +1 -1
- package/package.json +3 -2
- package/script/src/cli/mod.d.ts +3 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +968 -342
- package/script/src/cli/projectTooling.d.ts +138 -0
- package/script/src/cli/projectTooling.d.ts.map +1 -0
- package/script/src/cli/projectTooling.js +634 -0
- package/script/src/jobs/controller.d.ts +14 -1
- package/script/src/jobs/controller.d.ts.map +1 -1
- package/script/src/jobs/controller.js +54 -3
- package/script/src/jobs/events.d.ts +9 -1
- package/script/src/jobs/events.d.ts.map +1 -1
- package/script/src/jobs/events.js +15 -2
- package/script/src/jobs/mod.d.ts +1 -0
- package/script/src/jobs/mod.d.ts.map +1 -1
- package/script/src/jobs/mod.js +1 -0
- package/script/src/jobs/run.d.ts +20 -1
- package/script/src/jobs/run.d.ts.map +1 -1
- package/script/src/jobs/run.js +29 -4
- package/script/src/jobs/sanitize.d.ts +30 -0
- package/script/src/jobs/sanitize.d.ts.map +1 -0
- package/script/src/jobs/sanitize.js +97 -0
- package/script/src/mail/postal.d.ts.map +1 -1
- package/script/src/mail/postal.js +25 -20
- package/script/src/mail/sender.d.ts +5 -0
- package/script/src/mail/sender.d.ts.map +1 -0
- package/script/src/mail/sender.js +52 -0
- package/script/src/mail/service.d.ts.map +1 -1
- package/script/src/mail/service.js +7 -5
- package/script/src/next/jobs/route.d.ts.map +1 -1
- package/script/src/next/jobs/route.js +1 -1
- package/skills/loom/SKILL.md +38 -23
- package/skills/loom-db/SKILL.md +9 -7
- package/skills/loom-db/references/db-stack.md +2 -1
- package/skills/loom-jobs/SKILL.md +36 -6
- package/skills/loom-lingui/SKILL.md +38 -0
- package/skills/loom-lingui/agents/openai.yaml +4 -0
- package/skills/loom-mail/SKILL.md +14 -3
package/skills/loom/SKILL.md
CHANGED
|
@@ -15,10 +15,13 @@ project.
|
|
|
15
15
|
## Start here
|
|
16
16
|
|
|
17
17
|
1. Read `loom.json` first.
|
|
18
|
-
2.
|
|
19
|
-
|
|
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
|
-
|
|
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
|
|
56
|
-
|
|
57
|
-
`
|
|
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
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
|
163
|
-
|
|
164
|
-
- `loom dev sync` records the Loom source commit in the managed
|
|
165
|
-
|
|
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
|
|
173
|
-
still point at local Loom after
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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>)"
|
package/skills/loom-db/SKILL.md
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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
|
|
29
|
-
should use the app's env-aware
|
|
30
|
-
|
|
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
|
|
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
|
-
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
37
|
-
|
|
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`
|
|
148
|
-
and that the direct-runner file does not import `dotenv` or
|
|
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.
|
|
@@ -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`,
|
|
30
|
-
`POSTAL_WEBHOOK_PUBLIC_KEYS`.
|
|
31
|
-
|
|
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
|
|