plugins system + 1pass plugin #168

theoephraim · 2025-10-14T22:09:16Z

A ton going on here. Ideally would have broken this up more, but it was in figuring out the DX for plugin authoring that a lot of this became clear, so authoring the plugin, while building the plugin system, and the general changes around decorators, all together was how it was actually built.

creates a new plugin system, which can load plugins using a new @plugin decorator. These can be loaded from local files, installed node modules, https, or from npm
plugins will be able to register new root decorators, item decorators, data types, and resolver functions
plugins will be installed globally in the graph, no notion of limiting scope
formalizes decorators, and unifies their arguments with the existing value resolver system
- this is because many plugins will now be referencing existing config items, so we want it to be the same as referencing items within values
- this also enables arbitrary logic for required/sensitive/etc -- for example @required=eq($SOME_VAR, 'foo')
- have added a few utility resolvers (if, eq) and more to come
first version of a 1password plugin, along with docs

changeset-bot · 2025-10-14T22:09:20Z

🦋 Changeset detected

Latest commit: ff543cd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@varlock/1password-plugin	Major
@env-spec/parser	Patch
varlock	Minor
plugin-test	Patch
@varlock/astro-integration	Major
@varlock/nextjs-integration	Major
@varlock/vite-integration	Major
astro-example	Patch
example-repo	Patch
example-repo-init-sample-test	Patch
example-repo-init-test	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

theoephraim · 2025-10-14T22:11:07Z

example-monorepo/packages/plugin-test/.env.op

+#
+# # @initSimpleVault(id=vault1, key=SIMPLE_VAULT_ENCRYPTION_KEY)
+#
+# @plugin(./node_modules/@varlock/1password-plugin/dist/plugin.js)


we'll have an easier to way to reference installed node modules rather than using a path like this

it could be something like @plugin(node_modules:@varlock/1password-plugin)
or it could just be the default when no other protocol is provided @plugin(@varlock/1password-plugin)

local paths will start with ./ or ../ or /

registries (npm/jsr/?) will be npm:packageName@1.2.3

theoephraim · 2025-10-14T22:12:21Z

example-monorepo/packages/plugin-test/.env.op

+#
+# @plugin(./node_modules/@varlock/1password-plugin/dist/plugin.js)
+# # @plugin(https://varlock-plugins-registry.dmno.workers.dev/varlock-1password-plugin-0.0.0.tgz)
+# @initOpVault(id=v1, token=$OP_TOKEN, enableCliAuth=true)


most plugins will probably introduce a root decorator that will be responsible for initialization - which usually means setting options, and wiring up auth to env items. In many cases you may want to create multiple instances of a plugin like this.

Some plugins may not need one? Or could optionally rely on defaults if no init decorator was used

I think maybe they should all have it for consistency's sake, and the case where there's some sort of update which adds parameters to a previously "empty" init

I think forcing the user to have an init call could make sense in the case where we standardize the init call (something like @initPlugin). Otherwise it's up to the plugin to do whatever it wants, which could be no init decorator, or several decorators involved in setting things up correctly.

If we do that, the question is whether you allow the plugin to introduce any behavior at all before calling init.

theoephraim · 2025-10-14T22:13:10Z

example-monorepo/packages/plugin-test/.env.op

+
+OP_VAULT_NAME=example
+
+OP1=op(v1, "op://dev test/${OP_VAULT_NAME}/credential")


Example of new custom resolver. It is referencing the vault ids in the initOpVault calls. Nothing special or formalized involved though... plugins can track their own state and do whatever they want.

They can use their module singleton scope to do so. In the future, we'll likely add more hooks, so they could for example initialize or reset their state as part of the overall loading process

In this 1pass example, the vault IDs are optional, with id on both the init call and items defaulting to _default if not specified.

Note that we'll get schema errors before value resolution if ids are no good, because we require the ids to be static strings, so are evaluated early.

theoephraim · 2025-10-14T22:14:09Z

example-monorepo/packages/plugin-test/.env.schema

+
+# some description
+# @required=true
+# @docs(https://example1.com)


@docsUrl is now deprecated in favor of a @docs() function, which can be called multiple times. It also now supports both a URL and optional label. Multiple docs links across all definitions will all be combined together and included in generated types.

makes sense to me. I think since there are multiple deprecations in this release we should probably consider a proper minor (0.1.0?) release

So far my thinking has been that we bump up to 0.1.0 (or maybe 1.0.0?) when we reach a point where we are ready to guarantee stability, and otherwise just keep rolling with it. But open to other ideas. Should also probably write something about our versioning strategy somewhere in the docs?

this feels like at minimum a minor version to me. we're definitely not adhering to semver currently but normally you'd announce the deprecation in a minor version and remove it in a major

theoephraim · 2025-10-14T22:15:18Z

example-monorepo/packages/plugin-test/.env.schema

+# @defaultRequired=infer @defaultSensitive=false
+# @generateTypes(lang=ts, path=env.d.ts)
+#
+# @currentEnv=$APP_ENV


@envFlag=APP_ENV is now deprecated (although still works) in favor of @currentEnv=$APP_ENV

While this now uses the unified resolvers to reference another item, we add some limitations - it must be set to ref(SOME_VAR) (or the unexpanded equivalent), and SOME_VAR must be an item that is defined in the same file.

Doesn't change the DX in this case very much, but I do think as we have more of these that unifying the resolvers will make the overall DX much better.

is the new name to give us time to deprecate envFlag?

We could leave the name the same and still make it work, but I thought the decorator naming didnt really make as much sense. Like with @envFlag youre saying - the name of the env flag item is "APP_ENV". Whereas "$APP_ENV" really represents the value that it resolves to, so you're saying the @currentEnv is what $APP_ENV will resolve to (eg "dev")

yeah makes sense to me, probably good for us to draft some guidelines about these types of deprecations though

theoephraim · 2025-10-14T22:16:55Z

packages/env-spec-parser/src/classes.ts

-  }) {}
+  }) {
+    if (this.data.value) {
+      const expanded = expand(this.data.value!);


expansion now happens automatically within the parser library, rather than needing to be called explicitly

theoephraim · 2025-10-14T22:18:01Z

packages/plugins/1password/package.json

+  "scripts": {
+    "dev": "pnpm run copy-wasm && tsup --watch",
+    "build": "tsup && pnpm run copy-wasm",
+    "copy-wasm": "mkdir -p dist && cp node_modules/@1password/sdk-core/nodejs/core_bg.wasm ./dist",


1pass internal lib uses wasm and we need to copy it into our final dist folder, since we dont have any dependencies being loaded.

This is what nudged me in the direction of plugins usually being a folder with a package.json, rather than defaulting to a single file. We may still want to support the single file case for when a user wants to just do a little custom stuff, but any published plugins should be a full folder.

theoephraim · 2025-10-14T22:20:04Z

packages/plugins/1password/src/plugin.ts

+const PLUGIN_VERSION = plugin.version;
+const OP_ICON = 'simple-icons:1password';
+
+plugin.name = '1pass';


plugin is injected globally... its a bit awkward, but the best way I've found so far to inject in memory objects into dynamically imported code. Otherwise we'd end up re-bundling copies of our classes and functions into the plugin, and instanceof checks would not work.

theoephraim · 2025-10-14T22:21:21Z

packages/plugins/simple-vault/package.json

@@ -0,0 +1,55 @@
+{


ignore this whole thing for now. Need to figure out how we will deal with CLIs and plugins before this plugin can be useful.

maybe cherry pick it into another branch/PR?

philmillman · 2025-10-16T17:53:54Z