deathbyknowledge/gsv-package-development

GSV Package Development

Start From Package State

Use native shell on target: "gsv":

pkg list
pkg show <package>
pkg manifest <package>
pkg source status <package>

Do not invent source paths. Visible package source lives under /src/packages/<package-path>. When cwd is inside a package source tree, most pkg source commands can infer the package.

Create a User-Owned Package

Use the current user's repo owner unless the user explicitly asks for another owner:

pkg create --repo <username>/<repo> --template web-ui --enable
pkg create --repo <username>/<repo> --template command --enable

Then edit the mounted source under /src/packages/<package>.

Manifest Shape

Keep the manifest in src/package.ts. Browser apps use browser.entry, backends use backend.entry, and CLI commands use cli.commands.

Declare only the Kernel grants the package entrypoints actually need:

• use fs.* for filesystem work
• use repo.* for ripgit repository content
• use pkg.* only for package lifecycle operations
• use adapter/process/scheduler grants only when the code directly needs them

Capabilities are part of the package trust contract. Do not broaden them to make development convenient.

Edit and Validate

1. Read source before editing.
2. Make narrow changes.
3. Validate with package-local checks when available, such as TypeScript, tests, or a focused command run.
4. Inspect staged source changes:

pkg source status <package>
pkg source diff <package>

Source writes are staged per process for ripgit-backed package source. They are not installed or shared until committed.

Commit, Checkout, and Sync

Commit staged source edits:

pkg source commit <package> --message "short imperative message" --branch <branch>

Move an installed package to a committed ref:

pkg checkout <ref> <package>

Builtin package sync is a host CLI workflow after root/gsv has the desired source:

gsv packages sync

Pulling upstream, checking out a ref, and syncing are different:

• upstream pull refreshes a local ripgit source from a remote branch
• checkout moves the installed package pointer to a ref
• sync re-seeds and reassembles builtin packages from root/gsv

Pitfalls

• Do not treat staged package source edits as installed behavior.
• Do not commit package edits during review unless the user changes the task to authoring.
• Do not use raw GitHub URLs for custom GSV packages unless the package is intentionally backed by a GitHub upstream.
• Do not use broad grants because a syscall is nearby.
• Do not confuse host gsv packages sync with native package source commit/checkout.