[voiys]

# .env.schema
# @type=port
PORT=3000
# @sensitive @required
API_TOKEN=exec(`op read op://vault/api/token`)
AUTH_HEADER=concat("Bearer ", $API_TOKEN)

graph = await loadEnvGraph({ mode: 'shape' })
await graph.resolveEnvValues()

normal load:  runs the command   API_TOKEN = "tok_..."   AUTH_HEADER = "Bearer tok_..."
shape load:   runs nothing       API_TOKEN = unknown     AUTH_HEADER = unknown     PORT = 3000
              graph.shapeSkipped = [{ kind: 'resolver', name: 'exec', itemKey: 'API_TOKEN' }]

why

opening a repo has turned into a way to get attacked. from the last three months:

• CHAINDROP (august): an npm worm in 400+ packages that commits a .vscode/tasks.json and a .claude/settings.json into every repo it can reach, so "a developer can still be infected by just opening the repository"
• VS Code fixed six Workspace Trust and Restricted Mode bypasses in two releases (1.136.2 on sep 8, 1.141.1 on oct 13), two of them rated critical
• LiteLLM 1.107.0 (oct 21) collected "nonempty environment variables" on "a normal Python startup"

a .env.schema can run a command, call a secret store and download a plugin, and today the only way to learn what a schema says is to do all of that. the VS Code extension is safe only because it doesn't use varlock's loader at all. the shared core we talked about in #469 would use it, and so do varlock codegen and a type checker. shape mode is the load those can use on a folder someone just opened.

what a shape load never does

runs exec() or any resolver not marked pure, executes a root decorator (except @setValuesBulk on data written in the schema), opens the cache, downloads a plugin, reads the shell env, reads a named pipe.

the promise

for every item it says unknown, or exactly the value and errors a normal load gives. same for required and sensitive, unless that one is flagged unknown.

• shape-soundness.test.ts generates 1,200 schemas and loads each both ways. it fails on every seed if the unknown rules are removed
• outside the repo: 32,000 generated schemas, 0 mismatches. 165 public schemas, same types as codegen on all of them. 100 hand-written hostile schemas, 87 clean

what's left: plugins

of the 13 hostile schemas that aren't clean, one is a regex written to backtrack forever, which the calling program can defuse for itself (the mapper does). the other 12 are all the same thing: a plugin that is installed still runs its own code when loaded. you described the fix in #469 back in march:

A middle ground could be that a plugin need to expose a json manifest of what it adds. Since we control the whole plugin pipeline and all the plugins (for now), we can build tooling that generates it at build time to maintain a single source of truth.

that was a while ago, but i think it's the right answer, and this is where it plugs in: a plugin with a manifest never has to be imported in a shape load. i have a rough version for the 18 first-party plugins. not in this PR.

the small PRs came out of this

#1282 to #1288 were all found while building and testing shape mode: the fuzzer, the hostile schemas and the generated test above each turned up bugs that are also in a normal load.

other limits

• the generated schemas don't cover imports, forEnv, bulk values or plugins
• a skipped command is assumed to succeed
• a file behind an unknown enabled= condition keeps its items as if it surely exists

your call

the name shape, whether pure should be public plugin API yet, and whether shapeSkipped is public or internal.

includes the fix from #1286 so the generated test can't hang. i'll drop it once that merges.