webappwiz
Check whether the webappwiz package already covers a piece of infrastructure before writing it by hand or adding a dependency for it. Read this before writing any of: time, clocks, durations or timers; logging; id generation; CLI argument parsing; background tasks or queues; web workers; markdown parsing; typed event emitters; 2D geometry or spatial indexes; filesystem, env or process access; API keys, tokens, secrets or credentials; AbortSignal plumbing; disposable resources; browser scroll, animation frames or visibility. Also use when a release publishes to npm through GitHub Actions (`via: githubActions()`), when asked to update or upgrade webappwiz in a project, and whenever the user says webappwiz.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- webappwiz
- version
- 0.0.59
- description
- Check whether the webappwiz package already covers a piece of infrastructure before writing it by hand or adding a dependency for it. Read this before writing any of: time, clocks, durations or timers; logging; id generation; CLI argument parsing; background tasks or queues; web workers; markdown parsing; typed event emitters; 2D geometry or spatial indexes; filesystem, env or process access; API keys, tokens, secrets or credentials; AbortSignal plumbing; disposable resources; browser scroll, animation frames or visibility. Also use when a release publishes to npm through GitHub Actions (`via: githubActions()`), when asked to update or upgrade webappwiz in a project, and whenever the user says webappwiz.
03 SKILL.md 正文
Using webappwiz
webappwiz is the parts of a web app that get written again every time, behind
interfaces a test can replace. One package, one subpath per module. Before
writing any of that here, find out whether it already exists there.
Its README carries the whole catalogue, a table of every subpath and what it is
for. Read it from node_modules/webappwiz/README.md, or, in a project that has
not installed it yet, from
https://raw.githubusercontent.com/jaredjj3/webappwiz/main/packages/webappwiz/README.md.
Nothing in the table is close: say so in a line and write it here. Something is:
read that module's own README and the exports of its index.ts, and judge
against what is actually needed rather than the one-line blurb.
It fits
bun add webappwiz and import the subpath. There is no package entry point, so
import webappwiz/time, never webappwiz. Fakes live under /testing beside
what they replace.
It nearly fits
Do not vendor it, fork it, or patch node_modules. Write what this project
needs here so nobody is blocked, leave a TODO: webappwiz/<subpath> once <gap>
on it, and hand the gap over: print the block below and tell the user to give it
to an agent working on the webappwiz repo.
In `packages/webappwiz/<subpath>`: <the gap, in a sentence>.
Wanted by <this project> for <the usecase, concretely>.
What is there now: <the export that comes closest, and where it stops>.
What is missing: <the smallest change that closes the gap: one more method, a
widened parameter, another implementation of an interface>.
Called like: <the call site, written the way the caller wants to write it>.
Describe the gap and stop. Do not design the API in the handoff: that repo has a style guide and a review, and neither of them is here.
It does not fit
One line naming the subpath you read and why it is not the one, then write it here. A wrong module taken up is worse than one written twice.
Credentials
An API key, token or other secret a project's code needs comes from
webappwiz/creds. Code reads it through Credentials, over a list of
sources it chooses for each place the app runs; the first source with a
value wins. Never put a secret in source, a config file, a test, or a
command line, never write a .env file yourself, and never ask for one in
chat.
Which source, where
From most to least locked down:
- The system's secret store,
SystemSecretStore: the Keychain, Credential Manager, or a Linux secret service. Encrypted at rest, held apart from files and the environment, so no file read,envdump, child process, or agent sees a value. Use it on a person's machine, and only it.SystemSecretStore.forProject(), kept aswebappwiz:<project>: keys the app itself uses, like a Stripe test key. One project's keys are never another's.SystemSecretStore.device(), kept aswebappwiz: keys that belong to the person and serve many projects, like the tokens scry runs on. Wider reach, so only for keys that really are shared.
- A hosted secrets manager (1Password, Vault, AWS or GCP Secret
Manager), as a source of the app's own: any object with a
labeland an asyncget(name). Fetched at runtime and access-controlled. Use it where the app is deployed, when the project has one. - The environment,
Environment: how CI, containers and hosting platforms hand a deployed app its secrets. Every child process inherits it, and it shows up in crash reports and debug dumps. Use it where the app is deployed. On a person's machine it means exports in a shell profile, which every program they run can read, so leave it out of the development list. - A
.envfile,DotenvFile(path): plaintext on disk, one mistake from being committed, and read by any tool or agent that opens it. Use it only where a deploy target insists on one, never on a person's machine. Under Bun,.envfiles are loaded into the environment already, soEnvironmentcovers them there.
How the app tells development from production, and which sources each lists, is the project's choice: ask the user when the project does not already say. The usual lists:
import {
Credentials,
Environment,
SystemSecretStore,
} from "webappwiz/creds";
const credentials =
process.env.APP_ENV === "development"
? new Credentials([
await SystemSecretStore.forProject(),
SystemSecretStore.device(),
])
: new Credentials([new Environment()]);
const key = await credentials.require("STRIPE_SECRET_KEY");
A tool that reads only its environment, like Prisma, Vite or wrangler,
never calls Credentials. In development, run it through
bunx @webappwiz/cli creds run -- <command>, which hands it the stored
keys for that run alone, usually from a package.json script; never reach
for a .env file or an export to feed it.
Credentials is a source itself, so a fallback pattern of the project's
own is a list of lists: new Credentials([vault, new Credentials([new Environment(), new DotenvFile(".env")])]) reads the
vault, then the environment, then the file. forProject() finds the
store's name itself, so never write a project name into code. Take the
Credentials as a dependency, so a test hands in one over
FakeSecretStore from webappwiz/creds/testing.
Adding one
-
Name it in
.wiz/config.ts, by its environment variable name, with what it is for.creds addtakes any name, but a named one shows as missing until someone keeps it, so whoever clones the project knows it is needed:export default { credentials: { names: { STRIPE_SECRET_KEY: "Stripe, for checkout" } }, }; -
Run
bunx @webappwiz/cli creds listto see which are missing. It never prints a value. For each missing one, ask the user to runbunx @webappwiz/cli creds add <NAME>themselves, with--devicefor a key that is theirs rather than the project's: it asks for the value at a prompt that shows nothing, and refuses when there is no terminal, so you cannot and should not run it for them.creds remove <NAME>deletes one.
Nothing reads a value back out for you to see, and nothing should: do not
print one, log one, or look one up with the system's own tools
(security, secret-tool, cmdkey). Code that needs a value reads it
itself.
Publishing from GitHub Actions
A release whose npm packages publish via: githubActions() (from
webappwiz/ship) publishes from the generated workflow, with no token and no
2FA code. npm allows that only once each package has a trusted publisher
entry naming the repository and the workflow, and making one takes the
user's own npm login in a browser. You cannot do it for them, so when you
add via: githubActions(), or a ship fails with "npm refused the run",
guide the user through it:
- Have them run the project's trust command once:
bunx @webappwiz/cli ship trustwhen the release is declared in.wiz/ship.ts, or the project's own command that callsrelease.trust(). It runsnpm trust githubfor each package. - Tell them npm asks them to authenticate in a browser, and that ticking "skip two-factor authentication for the next 5 minutes" there lets the other packages go through without asking again.
- A package must already be on npm before it can trust anything, so a package that has never been published goes out once the old way first.
- Then they ship as usual. A package that already trusts another workflow fails, and the error says how to clear it.
Updating
bunx @webappwiz/cli update rewrites every webappwiz dependency under the
directory to one version, since they are released together and a project
running two of them at different versions is running a combination nobody
tested. The version is the one you invoked, which is what bunx is for.
Installed skills and copied rules are refreshed with it, and local edits to
those do not survive.
It edits manifests and stops. Nothing is installed until you run bun install
yourself, and nothing is verified until you run this project's typecheck and
tests.
What broke is read the same way as anything else here: the module's own README
and the exports of its index.ts, not the one-line blurb and not a guess. If
the new version dropped what this project was using, check the migrations below
first. For removals not covered there, that is a gap: leave the
local code working, and hand it over with the block above. Do not vendor,
fork, or patch node_modules to get the build green.
Migrating removed webappwiz/t and webappwiz/config
These modules have been removed in favor of Zod and ordinary typed settings. If the project imports either subpath, migrate those callers as part of the update. This is an intentional replacement, so do not request their restoration through the gap handoff above.
Add Zod as a direct dependency in each package importing it (bun add zod),
then replace import { t } from "webappwiz/t" with
import { z } from "zod". Primitive, object, array, enum, optional, and
nullable builders have Zod equivalents. Replace Infer<typeof schema> with
z.infer<typeof schema>; replace custom Schema implementations and
SchemaBase subclasses with Zod schemas, refinements, or transforms.
Check behavior at each input boundary:
.parse()and.safeParse()validate through Zod. ReplaceSchemaError.pathand.reasonwithZodError.issues, using each issue'spathandmessage. Forvalidate(schema, value), useschema.parse(value)when the schema is Zod; for other libraries, use their parser or the Standard Schema interface.- Zod has no per-schema
.coerce(raw)method. Usez.coerce.number().parse(raw)for numeric strings. Decode JSON strings before validating object or array schemas, handling malformed JSON too. webappwiz/cmdstill accepts Standard Schema. It passes strings to the schema, so numeric args and options needz.coerce.number(). Declare an on/off switch as.option("name", z.boolean(), { default: false }): it is false unless given,--name=falseturns it off, and a bare--namenever takes the next argument as its value.z.coerce.boolean()converts"false"to true and is not a replacement. Command validation remains synchronous and reports an ordinaryErrorwith the first issue's dotted path and message.- Zod numbers reject infinity. Object schemas still strip extra keys, but
missing optional properties are omitted rather than added as
undefined; their inferred object keys are optional too. Check callers that enumerate keys or rely on exact error wording.
Replace Config.factory(shape) with z.object(shape), config.get("key")
with typed property access, and config.toRecord() with the parsed object.
Use z.infer<typeof Settings> instead of InferConfig. If freezing matters,
wrap the parsed object in Object.freeze(), which preserves the old shallow
freeze. For example:
import { z } from "zod";
const Settings = z.object({
host: z.string(),
port: z.number(),
});
type Settings = z.infer<typeof Settings>;
const Environment = Settings.extend({ port: z.coerce.number() });
const settings = Object.freeze(Environment.parse(process.env));
const updated = Object.freeze(Settings.parse({ ...settings, port: 9090 }));
Keep environment decoding separate from strict settings validation when
replacing factory.coerce() and config.update(). Updates merge parsed
settings and revalidate them; do not rerun input transforms on their output
unless those transforms accept that output. Boolean and JSON environment
values need the explicit decoding described above.
After migrating, run the project's typecheck and tests, including invalid inputs, absent/defaulted options, boolean flags, and settings updates used by the project.
Rules
- Never edit the webappwiz repository from this project's thread.
- Never copy its source into this project.
- Reading the table is the whole check, and it is cheap. Do it before adding a dependency, not after.
04 同仓库更多 Skills
scry
Write, update, and remove the scry rules in this project's .wiz/scry, which `wiz scry` checks code against like a linter. Use when the user explicitly asks for a rule, or asks for a style or convention change across the codebase that a rule could enforce from now on ("stop using default exports", "comments should say why"). Also use when asked to scry a change or run `wiz scry`.
splates
Use the splates CLI to land your work on trunk, or a base branch given as an argument, from an isolated git worktree without pull requests. Read this before investigating anything that may lead to a code change in a splates repository, since it decides where the work happens, and whenever you need to add, claim, merge, remove, list, show, locate, or defer a task, or queue, pick up, link, or reorder a task for later, or work down a lane of them. Also read it before asking the user a question or proposing anything in a splates repository, with a task open or not.
shadcn
Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
scry
暂无简介