summary	read_when	system4d
Overview and quickstart for pi-little-helpers.	Starting work in this repository.	container compass engine fog Repository scaffold for a pi extension package. Ship small, safe, testable extension iterations. Plan -> implement -> verify with docs and hooks in sync. Unknown runtime integration edge cases until first live sync.

@tryinget/pi-little-helpers

A pi extension package with utilities for code block selection, package update notifications, and conversation stashing.

Install

pi install npm:@tryinget/pi-little-helpers

Extensions

Extension	Description
code-block-picker	Interactive code block selection from assistant responses
package-update-notify	Checks for updates to pinned npm/git packages in pi settings
stash	Manage conversation stashes for context switching

Shared utilities live in lib/package-utils.ts (used by package-update-notify).

Development

1. Clone and install:

   git clone https://github.com/tryingET/pi-little-helpers.git
   cd pi-little-helpers
   npm install

2. Pi auto-discovers extensions when working in this directory.

Runtime dependencies

This extension expects pi host runtime APIs and declares them as peerDependencies:

• @mariozechner/pi-coding-agent
• @mariozechner/pi-ai

When using UI APIs (ctx.ui), guard interactive-only behavior with ctx.hasUI so pi -p non-interactive runs stay stable.

Repository checks

Run:

npm run check

check routes to quality:ci via scripts/quality-gate.sh. It enforces structure validation, Biome lint checks, optional TypeScript typechecks, and npm pack dry-run.

Quality gate lane (TS)

• formatter/lint baseline:
  • biome.jsonc
  • .vscode/settings.json (Biome formatter + code actions on save for JS/TS/JSON)
  • pinned local binary via @biomejs/biome in devDependencies
• scripts/quality-gate.sh stages:
  • pre-commit
  • pre-push
  • ci
• npm script entry points:
  • npm run quality:pre-commit
  • npm run quality:pre-push
  • npm run quality:ci
• helper scripts:
  • npm run fix (auto-fix)
  • npm run lint (check-only)
  • npm run typecheck
• lane metadata:
  • policy/stack-lane.json

Release + security baseline

This scaffold defaults to release-please for single-package release PR + tag flow (vX.Y.Z), npm trusted publishing via OIDC, and deterministic release artifact checks.

Included files:

• CI workflow
• release-check workflow
• release-please workflow
• publish workflow
• release-check script
• Dependabot config
• CODEOWNERS
• release-please config
• release-please manifest
• Security policy

Trusted-publishing defaults captured in this scaffold:

• release-please uses vX.Y.Z tags (include-component-in-tag: false) to align with publish trigger logic.
• release-please action is pinned to an immutable v4.4.0 SHA.
• publish workflow and release-check workflow both upgrade npm (>=11.5.1) for consistent trusted publishing behavior.
• setup-node uses package-manager-cache: false to avoid implicit caching behavior changes from setup-node v5+.
• setup-node v6 / setup-python v6 / upload-artifact v6 require Actions Runner >=2.327.1 on self-hosted runners (GitHub-hosted runners already satisfy this).
• release-check script tolerates npm already published version dry-run responses for post-release idempotency.
• package metadata must include repository.url matching the GitHub repo for npm provenance verification.

Recommended before release:

npm run release:check
# quick mode for CI / no local pi smoke
npm run release:check:quick

Optional: add an executable scripts/release-smoke.sh for extension-specific smoke checks. release-check.sh will run it with isolated PI_CODING_AGENT_DIR and PACKAGE_SPEC env vars.

Before first production release:

1. Confirm/adjust owners in .github/CODEOWNERS.
2. Enable branch protection on main.
3. Confirm GitHub Actions repo settings:
   • workflow permissions: Read and write
   • allow GitHub Actions to create/approve PRs
   • allowed actions policy permits marketplace actions used by workflows
4. Configure npm Trusted Publishing for this repo + publish workflow.
5. If this is a brand-new npm package, perform one bootstrap token publish first, then add the trusted publisher in npm package settings.
6. Merge release PR from release-please, then publish from GitHub release.

Issue + PR intake baseline

Included files:

• Bug report form
• Feature request form
• Docs request form
• Issue template config
• PR template
• Code of conduct
• Support guide
• Top-level contributing guide

Vouch trust gate baseline

Included files:

• Vouched contributors list
• PR trust gate workflow
• Issue-comment trust management workflow

Default behavior:

• PR workflow runs on pull_request_target (opened, reopened).
• require-vouch: true and auto-close: true are enabled by default.
• Maintainers can comment vouch, denounce, or unvouch on issues to update trust state.
• Vouch actions are SHA pinned for reproducibility and supply-chain review.

Bootstrap step:

• Confirm/adjust entries in .github/VOUCHED.td before enforcing production policy.

Docs discovery

Run:

npm run docs:list
npm run docs:list:workspace
npm run docs:list:json

Wrapper script: scripts/docs-list.sh

Resolution order:

1. DOCS_LIST_SCRIPT
2. ./scripts/docs-list.mjs (if vendored)
3. ~/ai-society/core/agent-scripts/scripts/docs-list.mjs

TypeScript lane reference for pi extensions:

uv tool run --from ~/ai-society/core/tech-stack-core tech-stack-core show pi-ts --prefer-repo

Pinned lane metadata lives in policy/stack-lane.json.

Copier lifecycle policy

• Keep .copier-answers.yml committed.
• Do not edit .copier-answers.yml manually.
• Run from a clean destination repo (commit or stash pending changes first).
• Use copier update --trust when .copier-answers.yml includes _commit and update is supported.
• In non-interactive shells/CI, append --defaults to update/recopy.
• Use copier recopy --trust when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
• After recopy, re-apply local deltas intentionally and run npm run check.

Hook behavior

• Git hooks path is configured to .githooks by scripts/install-hooks.sh.
• .githooks/pre-commit runs:
  • scripts/quality-gate.sh pre-commit
  • check-only (auto-fix with npm run fix)
• .githooks/pre-push runs:
  • scripts/quality-gate.sh pre-push
• Repo-local commit workflow prompt:
  • .pi/prompts/commit.md

Live sync helper

Use scripts/sync-to-live.sh to copy extension entrypoints plus shared src/ modules into ~/.pi/agent/extensions/pi-little-helpers/.

Optional flags:

• --with-prompts
• --with-policy
• --all (prompts + policy)

After sync, run /reload in pi.

Docs map

• Organization operating model
• Project foundation model
• Project vision
• Project incentives
• Project resources
• Tech stack local override
• Contributor guide
• Extension SOP
• Trusted publishing runbook
• Next session prompt