@gadicc/loom
v2.3.1
Published
Shared helpers and verification tooling for Next.js applications.
Readme
loom
Shared TypeScript helpers for extracting common code from multiple Next.js apps.
This repo currently still lives in the gadicc directory, but the package name
is @gadicc/loom and the intended CLI name is loom.
Project status and support
Loom is primarily developed for the maintainer's own commercial and open source applications. Others are welcome to use it, but it is provided without warranty and without any commitment to support, compatibility, maintenance periods, or a particular roadmap. Releases follow semantic versioning so independently pinned consumer apps can upgrade deliberately.
Security issues should be reported privately as described in
SECURITY.md, not through a public issue.
Current feature set:
- shared DB stack scaffolding for Neon/Drizzle/Valibot/PGlite consumers
- shared jobs framework primitives for app-local
src/jobsimplementations - shared Next.js App Router jobs adapters for list pages, run pages, and route handlers
- auditable, scope-agnostic API-key authorization with an app-owned Better Auth adapter, managed audit schema, explicit jobs integration, optional MUI UI, Vercel country/IP snapshots, and bounded retention
- durable provider-neutral outgoing mail with atomic outbox leases, Postal transport and signed webhooks, per-recipient state, and admin-gated test mail
- a Loom-managed env runner for non-Next commands that need the same
.env*semantics as Next - consumer project tooling with Bun, npm, pnpm, Yarn and Deno task/dependency
ownership that supports
package.json,deno.json,deno.jsonc, and dual-config projects with separate task and dependency owners recorded inloom.json - Bun-primary BDD tests with an independent Deno parity gate
- native TypeScript compilation to ESM JavaScript, declarations and usable maps
License
Copyright © 2026 Gadi Cohen. Licensed under the Apache License 2.0.
The license includes warranty disclaimers and a limitation of liability; consumers remain responsible for determining whether Loom is appropriate for their applications.
Loom does not redistribute third-party agent skills. Its metadata-only catalog records reviewed upstream revisions and license evidence; consumer projects choose and cache the corresponding content directly from upstream.
Public npm package
Loom's public distribution is @gadicc/loom on npm:
pnpm add @gadicc/loom
# or: npm install @gadicc/loomConsumer projects do not need registry mappings or package-read tokens.
Maintainer bootstrap, trusted-publisher configuration, release verification, and
consumer migration are documented in
docs/npm-publishing.md.
CLI
loom now includes a small bootstrap CLI and feature-scaffolding entrypoint.
The detection, dual-config precedence, and safe task-composition contract is
documented in docs/project-tooling.md.
loom initadds@gadicc/loomto the authoritative dependency config, creates or updatesloom.json, records the authoritative task runner/config and dependency manager/config, refreshes the managed Loom bootstrap block inAGENTS.md, and ensures the managed.agents/skills/*links point at the installed@gadicc/loompackage, activates skills exposed by installed npm packages, and configures version-matched Next.js guidance when supported by the installed Next version. It also resyncs every active feature's scaffolds and Loom-managed files under the rule below. Like every Loom command that updatesloom.json, it patches only the changed members of an existing file, so the file keeps its formatting and key order.- Loom never overwrites a file with local edits.
loom init,loom add, and feature syncs create missing files and update a Loom-managed file only when they can prove it is unmodified Loom output, ignoring indentation, line wrapping, trailing commas and quote style: it matches the hashloom.jsonrecords under the feature'smanagedFiles(once recorded with the current canonical-form version, such asc1:, the only proof), or, for a file from before that record, Loom's output for the recorded configuration or the exact output of an earlier Loom release. Any other file is left alone and reported with a summary of the difference, andloom checkreports it too. To restore Loom's version, move app-specific code elsewhere, delete the file, and rerun the command. Tasks Loom owns by name (db:*,drizzle-kit,schema:gen,job,pwa:build, the Lingui tasks) follow the same rule, usingmanagedTaskshashes: an edited task is kept, andloom checkwarns with both values. loom addlists the shared features that the CLI can activate and shows a short description for each one.loom add <feature>activates one shared feature inloom.jsonand applies that feature's scaffolding without overwriting app-local wrappers.loom add authrecords app-owned Better Auth entrypoints, scaffolds missing thin client and route wrappers, and enables theloom-authskill link.loom add jobsactivates the shared jobs feature inloom.jsonand scaffolds any missing local jobs/admin route files without overwriting existing app-local wrappers, while also enabling theloom-jobsskill link.loom add dbactivates the shared DB feature inloom.json, adds the managed DB dependencies and tasks to their recorded configs, keeps the standardneon.ts/neonFull.ts/drizzle.config.ts/ PGlite test harness files as Loom-managed thin wrappers (an existing app file in one of those paths is preserved and reported until the app moves its code and deletes it), scaffolds the app-local fixture script entrypoint, and enables theloom-dbskill link.neonFullverifies remote TLS certificates and hostnames even when the selected URL containssslmode=require. Private remote CAs must be trusted explicitly, for example with process-startNODE_EXTRA_CA_CERTS; invalid certificates fail instead of falling back. The existing plaintext exceptions fordb.localtest.me,localhostand127.0.0.1remain, including their existing override of URL TLS settings. Database URL precedence is unchanged. TLS verification does not add SCRAM channel-binding support to the underlying driver. Remote IPv4 certificates must contain a matching IP subject alternative name. DNS-only multi-host URLs retain the driver's per-host verification. Empty or escaped hosts, extra unescaped@signs or fragments in the authority, IP-containing multi-host URLs and bracketed IPv6 hosts are rejected because the runtime cannot reliably bind their current driver routing to certificate identity; use an explicit DNS host or single IPv4 address.loom add filesactivates the shared files schema contract after the DB feature is active. It materializes the Loom-managed Drizzle schema blueprint into an app-local committed schema file, records the blueprint version and hash inloom.json, scaffolds app-local repository/storage/access/route files, and leaves migration generation to the app's normaldb:generatereview flow.loom add mailrequires active DB and auth features, materializes the message/delivery/event Drizzle schema, and scaffolds a working app-local repository, Postal transport, service, RSA-signed webhook route, fail-closed admin boundary, and (for MUI apps) mail log plus test/one-off-mail UI. When jobs is active it also scaffolds a drain job without rewriting app-owned catalogs or schedules. Loom never generates the migration.@gadicc/loom/mailowns provider-neutral enqueue/lease/retry/cancel/event orchestration and memory test adapters.@gadicc/loom/mail/postalowns the Postal HTTP and webhook contract,@gadicc/loom/next/mailowns the raw-body route handler, and@gadicc/loom/mui/mailowns optional serializable admin views. Keep the default sender structured with the required bare address[email protected]and optional display namePOSTAL_FROM_NAME=Example App. Configure Postal webhook verification with a JSON array of RSA public JWKs inPOSTAL_WEBHOOK_PUBLIC_KEYS; shared-secret emulation is unsupported.loom files local setupcreates or reuses a<project>-devMinIO bucket, creates a bucket-scoped access key, and writes canonicalFILES_S3_*values to gitignored.env.local. It works immediately afterloom add files, without R2 or Vercel.loom files local checkverifies bucket access. Ordinaryloom checkreports missing local Files values without connecting to storage.loom files r2 setupcreates or reuses private Cloudflare R2 buckets for Production and Preview, records the explicit Cloudflare account and storage policy inloom.json, replaces only the untouched generated storage stub, configures canonicalFILES_S3_*values in Vercel, and writes non-secret local MinIO defaults in.env.localby default. Use--local-provider r2for deliberately shared development storage or--local-provider noneto leave local storage unwired. Existing custom storage modules and credentials are preserved.loom files r2 checkverifies the selected Cloudflare account, bucket existence and private access, exact non-secret Vercel values in Production and Preview, the absence of Files credentials in Vercel Development, and the configured local MinIO endpoint/bucket. The same checks run throughloom check --network.loom add api-keysrequires active auth and DB features, materializes the versioned audit schema, scaffolds fail-safe policy/verifier/repository/action boundaries and user/admin pages, and links theloom-api-keysskill. It does not authorize existing routes, change jobs, or generate migrations.@gadicc/loom/apiKeysprovides typed scope registries, exact-match policy dispatch, credential extraction, fingerprints, authorization/audit contracts, country normalization, and bounded audit retention. It also provides a structurally typed Better Auth verifier that classifies scope misses asinsufficient_permission, shared name/expiry limits and validators, andwithBetterAuthApiKeyHttpPathsDisabledfor the plugin's HTTP endpoints, whichloom checkexpects indisabledPaths.@gadicc/loom/next/apiKeysadds App Router authorization, session-or-key composition, completion auditing, and explicit Vercel request context.@gadicc/loom/mui/apiKeysprovides optional lifecycle and audit UI.loom api-keys integrate jobs --resource <name> --action <name>records an explicit additive jobs authorization integration after the app has protected its HTTP jobs route with fresh session/admin policy. Direct local runners are unchanged and remain API-key-free.loom api-keys retention enablerecords the default 180-day/5,000-request retention policy. The app must transactionally implement the retention repository and schedule the shared runner; Loom does not silently create or modify jobs. Useretention disablefor an app-owned legal-hold workflow.loom add secretsactivates reversible secrets at rest. It records the module paths, key variable names and per-environment key lists inloom.json, scaffolds a thin app-local secrets module and a secret-locations module, links theloom-secretsskill, and writes a development key and pointer to gitignored.env.localwhen it holds neither. The development key is never printed, and existing variables are never changed. It also writesLOOM_SECRETS_ENVIRONMENT=developmentthere, so.env*.localfiles must be excluded from container images and deployments. A host other than Vercel setsLOOM_SECRETS_ENVIRONMENTin the platform's own environment, which takes precedence over.envfiles; where it andVERCEL_ENVname different environments, every secrets operation is refused.@gadicc/loom/secretsprovides sealed strings (ls1), keyed fingerprints (lm1), per-purpose subkeys, required bindings, environment and static keyrings, key fingerprints andassertReady()on Web Crypto.@gadicc/loom/secrets/legacyis a read-only reader for older(value, iv[, keyVersion])AES-GCM rows.@gadicc/loom/secrets/maintenanceprovidesreport, strictverifyandresealover app-declared locations.@gadicc/loom/next/secretswraps the runtime for Next.js and refuses to use keys during a production build. Seedocs/secrets-feature.md.loom secrets keygengenerates a key for Production (or--environment preview), prints the variable assignment and its fingerprint once, and always records the fingerprint inloom.jsonasactive, or asdecrypt-onlywhen an active key exists. It refuses to run unless its input and output are both terminals, and when the environment marks a CI or agent session, with no override. That is a guardrail, not a guarantee: it cannot tell who is at the terminal, so the rule the operator must still respect is that they run it personally, in their own terminal, never through an agent, a script or CI.- On a project linked to Vercel,
keygenoffers to add the key to Vercel Production as a Secret, and the pointer for an active key, after the operator pastes the key back from their password manager and it matches the recorded fingerprint.loom secrets push <id>does the same later, andloom secrets activate <id>offers to set the Vercel pointer before it changesloom.json.--vercelacts without the first question and--no-vercelnever acts; without either, only a person at a terminal is asked.keygenandpushreplace a pointer already on Vercel only on a yes at the terminal. loom secrets fingerprintreads a key from a hidden terminal prompt and prints only its fingerprint, to compare a saved copy withloom.json. It has the same session guardrail and refuses any argument: a key typed on the command line is in shell history and must be treated as exposed.loom secrets activate <id>records a listed key as active and the previous active key as decrypt-only;loom secrets retire <id>records a key that no stored value, keyed fingerprint or restorable backup needs as retired. Both changeloom.json; apart fromactivate's Vercel pointer offer, the deployment variables remain the operator's step. Set the pointer variable (LOOM_SECRETS_ACTIVE_KEY) on the platform before deploying aloom.jsonwith a newly activated key: a deployment that has the new list and the old pointer fails every seal, though opens still work. Deploy aloom.jsonthat retires a key before removing that key's variable.loom checkverifies the secrets modules and recorded key lists and reports a key value in any git-tracked file, by file and variable name. In a Next.js project the secrets module must import@gadicc/loom/next/secrets; the core entry point alone does not pass. If Git cannot search the tracked files it says so instead of passing. With--productionthat is a failure, and it also fails when no production key is recorded, or when an existing.github/vercel-production-env.jsonhas nokeyPatternrequirement that holds the keys to Sensitive, Production-only variables, or no requirement whosekeysinclude the pointer variable (LOOM_SECRETS_ACTIVE_KEYby default), without which a deployment cannot seal. The Sensitive and Production-only properties are enforced against Vercel metadata byloom db release prepare-build-env.@gadicc/loom/filesprovides the shared files runtime primitives: SHA-256 hashing, digest verification, metadata detection, repository/storage adapter contracts, in-memory test adapters, and headless upload helpers.@gadicc/loom/files/s3adapts an app-provided AWS SDK v3 S3 client to the shared storage contract without making AWS SDK packages Loom dependencies.@gadicc/loom/next/filesprovides App Router route-handler factories for uploads, metadata lookup, and downloads over app-provided persistence and storage adapters.loom add linguiadopts Lingui catalog tooling without owning locale routing or translations. It records loader versus precompile mode, adds compatible dependencies and extract/compile tasks, ignores generated JavaScript catalogs, and ensures precompiled catalogs are built before the app build.loom checkalso reports tracked generated catalogs, task-order drift, mismatched runtime imports, and missing Next.js loader/SWC wiring.loom add pwaactivates the shared Serwist PWA feature, adds the Serwist dependencies and build task, safely composes it after an existing Next build, scaffolds configurator-modeserwist.config.mjsplus worker/provider files, records whether the update prompt should use the MUI adapter or browser fallback, adds a 60-second update check interval for MUI installs, and ignores generated service-worker output.useLoomPwaInstallfrom@gadicc/loom/next/pwais an opt-in React hook for an app-owned install action. Mount it once in the persistent app shell;canInstalloffers a captured native prompt or iOS home-screen help,isIOSselects instructions, andisInstalledhides the action in app display modes or afterappinstalled. CallpromptInstall()directly from a click; it returnsaccepted,dismissed, orunavailable(show iOS help), and propagates errors for app-owned fallback UI. Native events are single-use. Detection cannot establish whether another browser window has installed the app. No persistent installed flag or automatic prompt is added. Shadowlang remains on its existing adapter until its next app update.loom add skillsadopts matching reviewed external skills into the gitignored.loom/skillscache, records exact revisions and content hashes inloom-skills.lock.json, and activates package-provided skills.loom statussummarizes the installed Loom package,loom.jsonstate, active features, local-dev sync state, and managed/recommended skill links.loom env -- <command> [...args]loads the consumer project.env*files with Next-compatible@next/envsemantics, preserves existing shell env precedence, then runs the command from the consumer project root. Use it for non-Next commands such as direct job runners, Drizzle, ad hoc DB inspection, and app scripts that need env. Next commands such asnext devandnext buildalready load.env*themselves.loom skills checkvalidates the project lock, external cache, and activation links.loom skills updateupdates adopted external skills to Loom's current reviewed immutable revisions.loom skills disable <name>opts out of automatic activation;enableclears the opt-out andsyncreactivates the skill.loom db fixturesruns the Loom-managed DB fixture dump entrypoint for the active DB feature, using the configuredscripts/dump-test-tables.tsand scripts tsconfig.loom db schema-genruns the Loom-managedvs_tocodeworkflow for the active DB feature and then refreshes the Valibot barrel file. Pass extra generator flags after--, for exampleloom db schema-gen -- --watch.loom db schemas syncre-materializes active Loom-managed schema blueprints into app-local schema files only when the file still matches the last recorded Loom hash. It refuses to overwrite local edits, updates simple schema barrel exports, and never generates Drizzle migrations.loom db neon setupprovisions a Vercel-managed Neon database for the active DB feature, connects it to the linked Vercel project for Production and Preview only, skips local env pulling, and records the provider policy inloom.json.loom db neon checkruns only the DB/Neon network checks: Vercel CLI availability, project linking, Neon resource connection, Production/Preview DB env vars, and the absence of DB env vars in Development.loom db release setup-githubcreates/updates the GitHubproductionenvironment for staged Vercel releases: it storesVERCEL_ORG_IDandVERCEL_PROJECT_ID, and saves a bounded project-scoped Vercel token as the GitHubVERCEL_TOKENenvironment secret. Reruns preserve an existing secret; use--rotate-tokenfor explicit replacement or--token-scope teamonly for compatibility. Its branch policy and the release checks usefeatures.db.config.release.productionBranchfromloom.json, defaulting tomain. See release configuration for other production branches and matching app-owned workflow/Vercel settings.@gadicc/loom/releasesuppliescreateGithubActionsOidcFetchfor masked, short-lived GitHub Actions identities scoped to one verified deployment origin. It refuses cross-origin requests and redirect following; the app owns health, application-auth and promotion assertions. See Trusted Sources adoption.loom checkgives non-blocking adoption guidance for legacy bypass references and duplicated OIDC acquisition in workflows and directly referenced scripts; it does not change provider settings or retire credentials. Deployment and promotion still use a separate Vercel API token.loom db release mask-env <env-file>runs in GitHub Actions right aftervercel pull(orprepare-vercel-project) and writes one::add-mask::command per pulled value that could be secret. It reads the file directly, so a process variable cannot shadow the file's value. It skips values shorter than 8 characters and names that are public by construction (NEXT_PUBLIC_*,VERCEL_GIT_*and a fixed list of Vercel system variables such asVERCEL_ENVandVERCEL_URL); every other name, includingVERCEL_AUTOMATION_BYPASS_SECRET,VERCEL_OIDC_TOKENandTURBO_TOKEN, is masked, and multi-line values are also masked line by line.loom checksuggests it in place of inline masking scripts.loom db release prepare-vercel-project production <env> <metadata> <project>materializes a private, consistency-checked Production env snapshot and exact.vercel/project.jsonfor a project-scoped token. After a standalone build, stage the prebuilt artifact withVERCEL_ORG_IDandVERCEL_PROJECT_IDremoved from that deploy process, then useloom db release promote-vercel <deployment-id>for bounded project API promotion and terminal readback.- With a capable native checkout,
loom dev local /path/to/loomfirst builds a verified app-private package under.loom/generated/<generation>/package.localthen selects and installs that package, preserving the published pin.syncbuilds a new physical path when source/version/content changes. Apps sharing a checkout keep independent versions and copies. Existingnpm/links migrate only through an explicitlocalactivation; building Loom alone does not move them. Install the checkout's frozen build dependencies first withbun install --frozen-lockfile --ignore-scripts. New private workflows require Linux with verifiable process identity. Exact pins and stable^/~full versions are supported; pin exact for other constraints. Compatible installed range versions are retained; changed incompatible ranges rebuild. loom dev local /path/to/loomenables local unpublished Loom development. It adds a managedfile:override for pnpm projects or a Denolinksentry indeno.json(c), then runs the local-dev sync flow when needed. The pnpm override goes where the project's pnpm version applies it (verified with real pnpm 9.7.0 to 11.25.0): pnpm before 10.5.1 reads overrides only frompackage.jsonresolutions/pnpm.overrides; pnpm 10.5.1 to 10.x readspnpm-workspace.yamloverridesonly while bothpackage.jsonmaps are empty and otherwise ignores the workspace map entirely; pnpm 11 reads onlypnpm-workspace.yaml. Loom uses a managed block inpnpm-workspace.yamlor an entry in the applicablepackage.jsonmap (creatingresolutionsfor older pnpm when needed). Unlinking removes only Loom's own entry with a minimal edit, plus a map only if Loom created it (recorded in.loom/dev-state.json); package.json is never restored from a snapshot.loom dev syncrebuilds the local Loom package when its package-relevant source content differs from the fingerprint the build recorded (builds without that record fall back to comparing timestamps), then runspnpm install(ordeno install) when the consuming app has not applied the override yet or its installed copy differs from the built package by file list or content. pnpm 10 and 11 re-import a local directory dependency on every install, and a plain install keeps every other locked version. The sync fails with an explanation if pnpm-lock.yaml does not record the override afterwards, and warns when the install added duplicate peer variants of one package version. Other Loom commands also run this sync automatically when the managed local-dev override is active; pass--no-syncto skip it. After a sync that refreshed the package,loom env -- <command>still runs its command (the sync's build and install output goes to stderr, so the command's stdout stays clean), while the noninteractive Node launcher restarts other commands once before dispatch to load fresh Loom code. Interactive terminals, unsupported launchers, debugger sessions and a second refresh retain status 75 and ask for a rerun. An arbitrary child exit 75 is never retried. Concurrent syncs in one project, andloom dev localorloom dev published, take turns through a gitignored.loom/dev-sync.lock: a waiting command re-reads the link and re-checks freshness after the first finishes and, if the Loom package it loaded was replaced meanwhile, counts that as a refresh (the bounded restart applies;loom envcontinues). Private generations use strict leases: a live or unknown holder is never replaced because of age. The installer guardian keeps other mutations blocked after cancellation until its outcome is proved. Success requires zero exit and disappearance of its Linux process group. After stopping all app dev, build and install processes, useloom dev recover-install --stopped, then sync to repair forward. Current config edits remain authoritative; recovery never restores a whole config snapshot. Scripts that deliberately escape the group are unsupported; unreaped zombies require a functioning reaper or environment repair. Legacy links keep their earlier coordination limits. Each Loom build records its provenance (the git commit it was built from, whether that checkout was clean and no package-relevant file was written while the build ran (even if reverted), and a digest of the packed output) in<selected-package>/.loom-build.json, which stays out of the packed package. Each sync also records the Loom source commit in gitignored.loom/dev-state.json(and in the managedpnpm-workspace.yamlblock when that holds the override) forloom statusandloom check.loom dev prune --stoppedexplicitly removes unused completed private generations after app processes have stopped. It keeps active, installed, locked and rollback targets plus two recent completed copies. Sync never prunes. Unknown, redirected, changed and incomplete builds are retained or refused for inspection; incomplete builds require manual diagnosis. Old readers must stop before cleanup. Cached copies alone do not block production.loom dev publishedremoves that managed local-dev override so the app can return to the published package version, once it has proved, from build provenance, that what is installed is published. It collects every local Loom target (the managed pnpm override, any hand-writtenfile:/link:Loom entry in thepnpm-workspace.yamloverrides:map and any localpnpm-lock.yamlresolution, or every Deno link to Loom) and refuses when they name more than one package. The target's build must record a clean commit and still match its recorded output digest, the installed copy must match that build (pnpmnode_modules, or a Denonode_modulescopy unlessnodeModulesDiris"none"), and for pnpm the lockfile must resolve Loom to it; otherwise it says to runloom dev sync, or to commit the Loom changes and runloom dev sync --force. The build's commit must then be reachable fromorigin/mainand either included in a semver release tag or package-equivalent to the latest semver release because only non-package files changed after that tag. The command switches the app to the exact published@gadicc/loomversion that covers it and removes every Loom override or link it found. Dev state and the checkout's current git state play no part. A pnpm link that was never installed needs no proof: when pnpm-lock.yaml and pnpm's record of node_modules (node_modules/.pnpm/lock.yaml) still hold the published Loom andnode_modules/@gadicc/loomlinks pnpm's store entry for that version, the command removes the overrides and keeps the pin. Anything less certain gets the full proof: an interrupted install, or a layout without anode_modules/.pnpmstore entry to check (node-linker=hoisted,enableGlobalVirtualStore, a customvirtual-store-dir). Deno links are always proved, since Deno reads a linked directory or copies it into node_modules on its next install or run. It also notices stale lockfiles that still resolve Loom to a local package even after the workspace override has been removed.loom checkverifies the recorded package/Deno configs,loom.json, the managedAGENTS.mdblock and.agents/skills/*links, and then runs feature-specific checks for active entries inloom.json, including jobs-wrapper validation plus DB runtime, script, Valibot-barrel wiring, and the production migration release flow for active DB installs, managed local schema validation for active files installs, and Serwist package, worker, provider, update-check interval, MUI-confirm, and build-script wiring for active PWA installs. The DB release-flow check expects Vercel automatic production Git deployments to be disabled invercel.jsonand a GitHub Actions workflow to pull Vercel production settings, build, upload a staged prebuilt production deployment, run a live migration credential preflight, rundb:migrateagainst the preserved production environment, then promote the staged deployment.loom check --networkalso verifies the required GitHub release secret/variables when that workflow exists. When.github/workflows/*.yml|yamlstill contains Loom's obsolete GitHub Packages registry/auth setup,loom checkrecommends removing it. The command also activates newly discovered npm package skills with a notice, warns when the managed local dev override is active, reports inlinedotenv/@next/envimports or DB/jobs tasks that bypassloom env --, warns when authoritative and secondary configs expose conflicting tasks, and warns when a Deno link orpnpm-lock.yamlstill resolves Loom to local source. If.loom/dev-state.jsonrecords a synced Loom commit while local Loom may still be in use (a local override, link or catalog entry, a local lockfile resolution, or an installed copy that is not provably the published package),loom checkalso explains whether that commit is unpublished or published in a newer exact Loom version than the app is pinned to; with--productionthat fails only while a link, override or local lockfile points at local Loom, not for an unproven installed copy alone. (A Deno node_modules copy is proven published whendeno.lockrecords no Loom link and resolves the pinned version from the registry.) Otherwise the record is stale:loom checknotes that it can be deleted and only advises a newer pin, and a recorded checkout that no longer exists never fails the check on its own. Pass--strict-skillsto turn missing skill recommendations into check failures. Pass--productionto make local Loom dev overrides, local lockfile resolutions, unresolved synced Loom commits, and DB migration release-flow gaps release-blocking failures. Pass--networkto also run registered feature network checks after the local project checks.
The current CLI scope is project bootstrap, validation, and feature-specific
scaffolding. Extracted feature hooks are added behind the same init, add,
feature subcommand, and check flows.
Consumer app release workflow
Consumer apps may stay in local Loom development mode during normal feature work:
loom dev local /home/dragon/www/npm/loom
loom dev sync
loom checkBefore pushing or releasing a consumer app, switch back to the published Loom package and run the production gate:
loom dev published
pnpm install
loom check --productionFor Deno-managed projects, replace the pnpm refresh command with deno install;
loom dev published prints the project-appropriate command. A lockfile linked
by earlier Loom versions through pnpm update --no-save keeps its local
resolution through a plain pnpm install; loom dev published detects that
case and explains how to restore it. Release-check suggestions move Loom between
published versions with a package.json edit plus pnpm install (or
pnpm add --save-exact for such a legacy lockfile), never pnpm update, which
would re-resolve Loom's dependencies. Apps that pin Loom through a pnpm catalog
("@gadicc/loom": "catalog:") keep that reference: Loom reads and pins the
version in the pnpm-workspace.yaml catalog entry and suggests editing it plus
pnpm install, since pnpm add would replace the reference.
Publishing Loom is only required when the app was synced against package-relevant Loom changes that are not already covered by a published semver tag. Publishing a new Loom version does not move other consumer apps; each app remains on its committed dependency config and lockfile until that app deliberately upgrades.
New app DB bootstrap
For a new Vercel app that needs the shared DB stack:
loom init
loom add db
vercel link
loom db neon setup
loom check --networkloom db neon setup runs the Vercel Marketplace install through the Vercel CLI
using Production and Preview environments only. It intentionally avoids
Development and uses --no-env-pull so local .env* files are not populated by
the integration. Pass --name <resource-name> to override the default
<project>-db resource name, --region <region> to select a supported Neon
Marketplace region such as sin1, or --plan <plan-id> if a new Marketplace
installation requires a specific plan id. When Neon is already installed for the
team, Loom omits --plan and preserves that installation's current plan. Neon
Auth is explicitly disabled by default because Loom's auth feature uses Better
Auth; pass --neon-auth only when the app intentionally wants Neon Auth too.
Network checks are line-based for now so they remain readable in CI logs:
[1/6] Checking Vercel CLI is available ......................... ok ✓
Using vercel.
[2/6] Checking Project is linked to Vercel ..................... ok ✓
Linked to Vercel project prj_...When stdout is an interactive terminal, Loom uses an updating progress line with
a progress bar and prints only problem checks at the end. This is disabled
automatically in CI and can be disabled explicitly with --no-progress. Use
--no-color to disable colored status output.
See docs/network-checks.md for the hook design and
future expansion notes.
AI skills
The package now publishes Codex skill folders under skills/.
skills/loomprovides global loom guidance for consumer apps, centered onloom.json, feature activation, shared-vs-local ownership boundaries, and a small set of shared consumer-repo policies such as verification, documentation/comments, and commit-message expectations. Consumer repos keepAGENTS.mdsmall and use a managed Loom block there to route work into this shared skill.skills/loom-torvalds-reviewadapts the externallinus-torvalds-skillreview method to web apps, shared packages, CLI code, native code, and explicit prototypes. It keeps the upstream emphasis on correctness, compatibility, evidence, and simplicity while disabling literal kernel/C rules outside their real prerequisites.skills/upgrade-depsprovides a staged Deno and JavaScript/TypeScript dependency-upgrade workflow covering compatibility groups, rollback safety, failure isolation, major migrations, reviewable commits, and exact-tree final verification.skills/modernize-appguides staged modernization of an existing application, including identity/data preservation, optional offline/media transitions and verified rollout. Dependency-only work stays withupgrade-deps; new apps use scaffolding rather than this migration workflow.skills/loom-dbprovides DB-feature guidance for Neon/Drizzle wiring, managed local schema blueprints, Valibot generation, and the shared PGlite harness.skills/loom-authcovers Better Auth secrets, rotation, environment trust boundaries, and proxy-aware localhost OAuth configuration.skills/loom-jobsprovides jobs-feature guidance for app-local catalogs, admin route wrappers, and shared helper wiring.skills/loom-api-keysprovides API-key adoption, authorization, audit, Vercel geolocation, UI mapping, jobs integration, and retention guidance.skills/loom-secretsprovides secrets-feature guidance for purposes and bindings, key custody and rotation, and the maintenance operations, including that agents do not generate production keys.
Projects do not need to copy these files manually. loom init, loom add db,
loom add jobs, and loom check manage a small project-local AGENTS.md Loom
block plus .agents/skills/* symlinks that point to the installed
node_modules/@gadicc/loom/skills/* folders. The global loom,
loom-torvalds-review, upgrade-deps, and modernize-app skills are linked
for every initialized project; feature skills are linked when their matching
feature is active.
Third-party skills are not packaged with Loom. Loom carries a metadata-only
catalog containing source URLs, immutable commits, content hashes, and license
evidence. loom add skills installs applicable reviewed skills directly into a
consumer project's gitignored .loom/skills cache and records the selection in
the committed loom-skills.lock.json. Missing or unclear licenses require the
explicit --accept-unknown-license <name> flag. loom skills migrate replaces
legacy symlinks from older Loom releases, while preserving custom local skill
directories.
Loom also scans installed npm packages for a root SKILL.md, skills/*, or
.agents/skills/*. New package-provided skills are activated automatically by
loom init, loom skills sync, and ordinary loom check, with a notice that
includes loom skills disable <name> as the opt-out path.
Bun consumer tooling covers detection, recorded task/dependency ownership and feature tasks. Managed local/sync/published workflows support the verified standalone Bun text-lock v2/v3 config1 and project-local isolated store (Bun 1.4.3; retained v2/1.4.2 profile), retaining the published dependency pin. Workspaces, global stores, unsupported locks and unowned overrides fail closed. See consumer tooling for supported commands and limitations.
Local testing of unpublished Loom changes does not require a Loom release. Keep
the consumer in loom dev local mode, run loom dev sync after changing Loom,
then run the consumer's recorded test, development, or build task. Tasks that do
not invoke Loom do not automatically sync its installed copy. A non-env Loom
command that still exits 75 after the noninteractive Node launcher's bounded
refresh needs a rerun. Use loom dev diagnose to inspect paths, versions and
freshness without syncing. See the
bootstrap runbook
when an older installed CLI cannot perform the initial sync. Switch with
loom dev published and pass loom check --production before an app release,
CD build, or push that triggers production. See the
toolchain and local-development roadmap for the
staged Bun evaluation and remaining workflow work.
For local Loom package development, prefer loom dev local and the managed
file: marker flow over pnpm link. loom dev sync owns the rebuild and pnpm
refresh step for that local package. When it refreshes the installed package at
the start of another Loom command, the noninteractive Node launcher hands off
once to the fresh CLI before dispatch. If it cannot do that safely, it returns
status 75 and asks for a rerun. loom env is the exception: it only loads env
files before starting its wrapped command in a new process, so it continues.
This keeps the committed dependency on the published version while still
resolving peer dependencies correctly during local development. Treat this as a
workaround for current pnpm behavior rather than a permanent preference; if
pnpm's local-link behavior changes, this flow can be simplified or removed
later.
The managed local-dev block also records the Loom source commit that was synced
when the local package path points at a Loom git checkout, and the same state is
persisted in gitignored .loom/dev-state.json so loom check can still
diagnose stale local lockfiles after the workspace override has been removed.
That record is informational, and loom dev published deletes it once nothing
local is in use any more (for pnpm, typically when rerun after the
pnpm install it asks for). loom dev published gates on the provenance the
installed build itself records in its selected package’s .loom-build.json: a build from a clean
commit that has reached origin/main and is either included in a semver release
tag or has no package-relevant changes after the latest semver tag can be
switched to the exact published version, while dirty, unreleased or unrecorded
builds block the switch. Builds from before Loom recorded provenance are rebuilt
by the next loom dev sync.
Loom's external catalog currently recommends these defaults:
ai-sdkfind-skillsfrontend-designlinus-torvalds-skill(with Loom's context-aware review companion)vercel-composition-patternsvercel-react-best-practices
It adds these dependency-matched recommendations:
better-auth-best-practicesfor projects that depend on Better Auth packagespnpmfor projects that use pnpmvitestfor projects that use Vitest
Next.js is handled separately because current Next releases ship documentation
matching the installed framework version under node_modules/next/dist/docs.
Loom adds a managed AGENTS.md pointer to those docs. Older Next releases can
use the official npx @next/codemod@latest agents-md fallback; migration
removes the retired next-best-practices symlink.
See docs/project-skills.md for lock/cache semantics,
package discovery, opt-outs, collision behavior, and migration details.
Jobs framework
The shared jobs code is designed so each app keeps its own jobs in
src/jobs/*.ts, while the shared package owns the common controller, catalog,
execution, formatting, and direct-run helpers. Keep metadata in a
dependency-free module and use createLazyJob in the executable catalog so
constructing an HTTP or direct-run catalog does not initialize every job's
transitive dependencies.
Example app-local job:
import type { Job } from "@gadicc/loom/jobs";
import { testMeta as meta } from "./indexWithMetaOnly";
export { meta };
export const handler: Job["handler"] = async (job) => {
job.log("hello");
};Example dependency-free metadata and lazy catalog entry:
// indexWithMetaOnly.ts
import type { Job } from "@gadicc/loom/jobs";
export const testMeta: Job["meta"] = {
id: "test",
desc: "Example job",
};
// index.ts
import { createLazyJob } from "@gadicc/loom/jobs";
import { testMeta } from "./indexWithMetaOnly";
export const test = createLazyJob(testMeta, () => import("./test"));Job output can be sanitized once at the execution boundary so the same policy applies to NDJSON, text, HTML, direct runners, HTTP responses, and app-provided formatters:
import { createJobOutputRedactor, type Job } from "@gadicc/loom/jobs";
import { createJobsRouteHandler } from "@gadicc/loom/next/jobs/route";
const providerToken = process.env.PROVIDER_TOKEN;
if (!providerToken) throw new Error("PROVIDER_TOKEN is required");
const outputSanitizer = createJobOutputRedactor(
new Map<string | RegExp, true | string>([
[providerToken, true],
[/Bearer\s+\S+/gi, "Bearer [REDACTED]"],
]),
);
export const jobsRouteHandler = createJobsRouteHandler({
catalog: jobs as readonly Job[],
handlerErrorMessage: "Job execution failed.",
outputSanitizer,
});Redaction rules run in map insertion order, each against the preceding rule's
result. Exact strings match wherever they occur. RegExp rules replace every
match without using the caller's lastIndex, even when the expression is
non-global or sticky. A true replacement means [REDACTED]; string
replacements are literal, so $&, $1, and $$ are not expanded. Empty exact
matchers are rejected without printing configured match or replacement values.
The sanitizer visits every string value emitted through job.log(), all other
log levels, and job.json() while retaining normal JSON behavior for arrays,
objects, dates, numbers, booleans, and null. Inputs are not mutated. If a
sanitizer throws or returns a non-string, Loom fails the execution closed and
emits only Job output sanitation failed. for that failure.
Output redaction and unexpected-error disclosure are separate. Omitting
handlerErrorMessage retains Loom's existing full-stack fatal event; supplying
a string emits that exact generic literal instead. Deferred-task errors keep
their own deferredTaskErrorHandler, and the additive
runDeferredTasksWithResult() method returns a failure count while
runDeferredTasks() keeps its legacy Promise<void> contract. Consumers that
run deferred tasks inline can emit a generic event from that callback; tasks run
after a response stream closes should report through a separate safe sink.
cancellationMessage: false suppresses the legacy Job cancelled event when
cancellation must only set the controller flag.
This boundary protects Loom job-event output only. It does not sanitize
console.*, provider or framework logs, audit metadata, request URLs, thrown
values retained in execution.result, or external logging systems. Object
property names are JSON structure rather than string values and are not
rewritten; do not place secrets in keys.
For the strongest Next.js deployment boundary, mount jobs in static route files
with createJobRouteHandler({ job }). A dynamic [id] route is one serverless
function and therefore still traces every implementation reachable from its
catalog, even when createLazyJob prevents unrelated modules from evaluating at
runtime.
Loom can manage those file-based entrypoints from the Jobs config in
loom.json:
{
"staticRoutes": {
"handlerFactoryExport": "createHttpJobRouteHandler",
"jobs": {
"example": "@/jobs/example",
"short-example": {
"module": "@/jobs/short-example",
"maxDuration": 300
}
},
"maxDuration": 1800,
"routeDirectory": "src/app/admin/jobs"
}
}Run loom add jobs after changing the map. Loom creates, updates, and removes
only wrappers bearing its managed marker; an existing unmanaged route is
preserved and reported. loom check verifies the generated set and its direct
literal maxDuration exports. The default is Vercel's current 30-minute maximum
of 1800, while staticRoutes.maxDuration and each job's optional
maxDuration override keep shorter limits explicit and checkable.
Repository testing
Bun 1.4.3 is the primary test runner during a staged migration. Run
bun install --frozen-lockfile --ignore-scripts, then bun run test or
bun run check. Before full checks, also install the isolated DB contract peers
with bun install --cwd scripts/fixtures/db-harness --frozen-lockfile --ignore-scripts
and bun install --cwd scripts/fixtures/test-resources --frozen-lockfile --ignore-scripts.
Full checks cover Oxfmt formatting/import order, Oxlint rules, production types,
the Bun suite, real DB harness contracts and the retained Deno/package gate.
Run bun run format to write formatting and import sorting,
and bun run lint:fix only when explicit safe lint fixes are wanted. See the
quality-tooling guide for editor setup, exceptions and
protected import order. See testing for
targeted tests, DOM setup, watch mode and dependency-parity rules. Run
bun run build to generate the npm artifact; deno task build runs the same
compiler. Both require the frozen Bun install. The approved next major publishes
ESM JavaScript with declarations for Node >=22.13.0 and TypeScript >=5.9;
see the migration guide. Consumer tooling stays
independently recorded.
Opt-in source development
Generated local mode remains the default. loom dev source --watch can mirror
Next.js library source from the managed local checkout without repeated package
builds/installs. It requires the withLoomSource(nextConfig, import.meta.url)
Next config wrapper. The installed compiled CLI/assets stay authoritative;
loom dev generated rebuilds before removing source activation, and
loom dev published retains the existing release proof. See the
source workflow and recovery guide
for scope, peer/dependency resolution, watcher/reinstall recovery and production
blocking. This does not change published exports to TypeScript or migrate apps.
