Skip to content

TypeScript ​

The TypeScript plugin toolkit. finn ships plugins to three hosts – Obsidian, VS Code, and Claude Code – and this module gives each of them the same on-demand loop: scaffold a correct skeleton, pin the host's api at the exact installed version so an agent writes against real types and not a hallucinated or newer surface, then reload the built plugin into its host to exercise it rather than assume it works. It is three small Nushell scripts over a templates/ tree, and it is deliberately passive – it writes files, it never installs or builds, that half is yours to run after.

In Practice ​

The three scripts are one loop. You scaffold a skeleton, run the install and build yourself, pin the api you are about to code against, then reload the result into its host and iterate.

Scaffold a plugin skeleton. You want a new Obsidian plugin that starts correct instead of from a blank directory, so you run:

nu .claude/stack/ts/scaffold.nu new obsidian-plugin my-plugin

It copies the obsidian-plugin skeleton out of templates/, substitutes __NAME__ for my-plugin in every file, and writes the tree into a new directory:

scaffolded obsidian-plugin as my-plugin into .\my-plugin, 6 files, run npm install then npm run build

That leaves a working manifest, an esbuild config, a tsconfig.json, and a Plugin stub that registers one say hello command – all with finn's conventions baked in. Pass --dry-run to print what it would write without touching disk, or --out ../projects to land it elsewhere.

Pin the api surface. Before writing against the Obsidian api you snapshot the installed typings so the agent references the real version, not a guess:

nu .claude/stack/ts/pin-api.nu pin obsidian

It reads the version out of node_modules/obsidian/package.json, copies obsidian.d.ts into .claude/api/ cold storage under a version-stamped name, and stamps a header on top:

// pinned obsidian api surface, version <version>, snapshot <date>, regenerate with pin-api.nu when the package updates

The file lands as .claude/api/obsidian-<version>.d.ts. It refuses to overwrite an existing pin unless you pass --refresh, and if the typings are not installed it stops with obsidian.d.ts not found ..., run npm install first rather than pinning nothing.

Reload into the host. With the plugin built, you exercise it instead of assuming it works:

nu .claude/stack/ts/reload.nu obsidian --vault "C:/vaults/test" --id my-plugin

It copies the built assets into the test vault's plugin folder and prints the one step it cannot script:

copied main.js, manifest.json into <vault>/.obsidian/plugins/my-plugin
now reload obsidian, the command palette Reload app without saving, or toggle the plugin off/on in settings

The copy is the automatable half; the actual reload is a keystroke in Obsidian, so the script does the copy and names the step rather than pretend it did more.

An example outcome. Three commands and a build later you have a real Obsidian plugin sitting in a test vault, coded against the exact typings you pinned, one reload away from running – and nothing on the machine was installed or activated that you did not run yourself.

The Three Targets ​

Every script is organised around the same three plugin hosts, though not all three earn every step – a Claude Code plugin is markdown and JSON, so it has no typings to pin.

TargetSkeleton (scaffold.nu)Pinned typings (pin-api.nu)Reload (reload.nu)
Obsidian pluginobsidian-plugin – manifest, esbuild config, a Plugin stubobsidian – node_modules/obsidian/obsidian.d.tscopies main.js / manifest.json / styles.css into the vault, prints the reload keystroke
VS Code extensionvscode-ext – package.json contributes, an activate / deactivate stubvscode – node_modules/@types/vscode/index.d.tslaunches the extension host via code --extensionDevelopmentPath, or prints the F5 step
Claude Code plugincc-plugin – the .claude-plugin/plugin.json and a command stub– none, no typings surface to pinreinstalls the folder into ~/.claude/plugins/<name>, notes to restart Claude

Key Files ​

scaffold.nu ​

The scaffolder – new <target> <name> copies the matching skeleton out of templates/, replaces __NAME__ with the given name in every file, and writes the tree to <out>/<name>. list prints the available targets, --dry-run prints what it would write without writing, and --out redirects where the project lands. It writes files and nothing else, then tells you to run npm install and npm run build yourself.

pin-api.nu ​

The typings pinner – pin <target> reads the installed .d.ts out of node_modules, reads the package version alongside it, and saves a version-stamped, dated copy into .claude/api/<target>-<version>.d.ts. It knows two targets, obsidian and vscode, refuses to re-snapshot an existing pin unless you pass --refresh, and degrades cleanly to a run-npm-install-first message when the typings are absent.

reload.nu ​

The reload loops – one subcommand per target, each doing the automatable half of the loop and printing the manual step where a reload cannot be scripted. obsidian copies the build into a test vault, vscode launches the extension host on the current directory, and cc-plugin reinstalls the plugin folder into ~/.claude/plugins (skipping node_modules). Each one degrades cleanly when its target or tooling is missing, falling back to the manual instruction.

templates/ ​

The skeletons – one directory per target, each a minimal but correct project with finn's conventions baked in: tabs, an ascii-only source, and a working build script, with __NAME__ left as the single substitution token. This is exactly what scaffold.nu new copies and rewrites, so a new plugin never starts from a hand-rolled manifest.

README.md ​

The map and the pull rules – documents the three scripts and their usage, and carries the two pull rules meant to be pasted into the target CLAUDE.md: read the pinned surface under .claude/api/ before calling an Obsidian or VS Code api, and start a new plugin from scaffold.nu new rather than hand-rolling the manifest and build config.

Connects to ​

  • Placed by the installer – the whole pack installs into a target project's .claude/stack/ts/ as one part, which is why every command in the docs is invoked as nu .claude/stack/ts/<script>.nu.
  • Feeds the memory layer – the lesson store keeps a ts domain, so gotchas hit while building Obsidian or VS Code plugins are captured and read back the next time you touch the same target.
  • Writes into the context layer – a pinned api lands in .claude/api/ cold storage and its pull rule goes into the target CLAUDE.md, making the exact installed surface authoritative for the agent, the same not-a-source-of-truth-until-verified discipline the rest of the context files follow.