@spences10/pi-tool-guidance 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Spence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @spences10/pi-tool-guidance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- package-readme:header:start -->
+
+[![built with Vite+](https://img.shields.io/badge/built%20with-Vite+-646CFF?logo=vite&logoColor=white)](https://viteplus.dev)
+[![tested with Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev)
+[![npm version](https://img.shields.io/npm/v/@spences10/pi-tool-guidance?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@spences10/pi-tool-guidance)
+[![license](https://img.shields.io/npm/l/@spences10/pi-tool-guidance)](https://www.npmjs.com/package/@spences10/pi-tool-guidance)
+
+![my-pi package preview](https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png)
+
+<!-- package-readme:header:end -->
+
+## Tool workflow guidance
+
+Distributes native Pi skills and concise system-prompt reminders for
+nopeek, Omnisearch, SQLite, and language-aware validation. It does not
+depend on the maintainer's local files.
+
+## What ships
+
+- `my-pi-nopeek`: one-shot credential loading, explicit key
+  allowlists, separate-shell limitations, and output disclosure
+  precautions.
+- `my-pi-omnisearch`: tool discovery, source extraction, and verified
+  research.
+- `my-pi-sqlite`: schema inspection, bounded queries, backups,
+  transactions, and respecting database safety gates.
+
+Pi advertises these native skills and loads their full contents on
+demand. Invoke `/skill:my-pi-nopeek`, `/skill:my-pi-omnisearch`, or
+`/skill:my-pi-sqlite` to request one explicitly.
+
+Essential reminders are contributed through a named structured prompt
+section. Secret guidance is active with shell access; MCP guidance is
+conditional on reachable tools or Pi's configured indirect-server
+listing. Both codemode and tool-search exposure work without requiring
+direct tool declarations.
+
+## Language-aware validation
+
+When editing and shell tools are reachable, the prompt reminds the
+agent to use the project's configured linter, type checker, Svelte
+tooling, and tests for code correctness. Coding-preference regexes
+remain workflow/text policies; Svelte guardrails block `$effect` by
+default, with explicit user-controlled exceptions. No parser,
+classifier gate, new validation tool, or automatic command execution
+is added.
+
+Use native Codemode to coordinate existing tools:
+
+1. Read project instructions and package scripts to select the
+   affected checks; do not assume every project uses the same
+   commands.
+2. Apply edits through `tools.edit()` / `tools.write()` and await them
+   before checking. Native nested calls retain the same guardrail
+   hooks as direct calls; do not scan the outer JavaScript as source
+   code.
+3. Run independent checks together only when they do not share mutable
+   outputs. Keep dependent edits, builds, and checks sequential.
+4. Inspect exit codes and tool errors, then summarize diagnostics. Do
+   not infer success from a fulfilled promise: `bash` resolves even
+   when its command exits nonzero.
+5. Correct the findings and rerun affected checks before reporting
+   completion. Code validation runs after the edit; it is not an
+   atomic pre-write security boundary.
+
+For example, after choosing this repository's `check` script:
+
+```js
+const result = await tools.bash({
+	command: 'pnpm run check',
+	timeout: 120,
+});
+text({
+	exit_code: result.exit_code,
+	truncated: result.truncated,
+	output: result.output.slice(-12000),
+	full_output_path: result.full_output_path,
+});
+if (result.exit_code !== 0) throw new Error('Project checks failed');
+```
+
+Inspect omitted output before diagnosing a failure. For multiple
+independent tool calls, `Promise.allSettled()` preserves successful
+results when another call rejects; inspect each result as well as each
+command's exit code. Codemode is orchestration, not a syntax checker
+or a way around guardrails. No classifier or paid model call is
+needed.
+
+## User configuration remains yours
+
+The package does not install the nopeek CLI, start MCP servers, set
+provider credentials, or modify `SYSTEM.md`, `APPEND_SYSTEM.md`, or
+`mcp.json`. Configure the required tools through Pi's normal
+mechanisms. Native prompt files coexist with the package's section;
+disabling this extension removes its bundled resources on reload in
+my-pi.
+
+Instructions are guidance, not a security boundary. Child processes
+can still print secrets; redaction and database permission enforcement
+remain separate. Third-party extensions that force a complete prompt
+can hide later structured sections; prefer Pi's structured prompt API.
+
+Bundled into my-pi as `tool-guidance`. Use
+`/extensions disable tool-guidance` to remove its reminders and
+bundled skills on reload. The package manifest exposes the same skills
+in standalone Pi.
+
+## Install
+
+<!-- package-readme:install:start -->
+
+```bash
+pi install npm:@spences10/pi-tool-guidance
+```
+
+<!-- package-readme:install:end -->
+
+## Development
+
+<!-- package-readme:development:start commands="check,test,build" -->
+
+Package scripts build transitive workspace dependencies first, then
+run local tools through Vite+ with `vp exec`.
+
+```bash
+pnpm --filter @spences10/pi-tool-guidance run check
+pnpm --filter @spences10/pi-tool-guidance run test
+pnpm --filter @spences10/pi-tool-guidance run build
+```
+
+<!-- package-readme:development:end -->
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { BuildSystemPromptOptions, ExtensionAPI } from '@earendil-works/pi-coding-agent';
+type Tool = Pick<ReturnType<ExtensionAPI['getAllTools']>[number], 'name' | 'exposure' | 'namespace'>;
+export declare function tool_guidance(options: BuildSystemPromptOptions, tools: readonly Tool[]): string;
+export default function tool_guidance_extension(pi: ExtensionAPI): void;
+export {};

package/dist/index.js

@@ -0,0 +1,56 @@
+const NOPEEK_GUIDANCE = `## Secret-safe commands
+Never read secret files or print credential values into model context. Read the bundled my-pi-nopeek skill before credential-dependent commands. Use one-shot nopeek run with only the required keys; separate Pi shells do not share loaded environment changes. Child-process output can still leak secrets; redaction is best-effort, not a guarantee.`;
+const OMNISEARCH_GUIDANCE = `## Web research
+For research and current external facts, prefer the configured Omnisearch MCP server. Read the bundled my-pi-omnisearch skill. Discover its actual tools with tool search or codemode, and read source content before presenting claims; snippets alone are not verification.`;
+const SQLITE_GUIDANCE = `## SQLite databases
+Prefer the configured SQLite MCP tools over ad-hoc shell SQL. Read the bundled my-pi-sqlite skill; inspect schema before querying, keep result limits small, and prefer a backup plus an explicit transaction before authorized writes. Do not bypass safety gates to make destructive operations easier.`;
+const VALIDATION_GUIDANCE = `## Language-aware validation
+Use the project's configured linter, type checker, Svelte tooling, and tests for naming and language correctness. Regex guardrails enforce workflow or explicit local policy, not syntax. After edits, run the affected checks. When codemode is available, use it to coordinate independent checks and summarize diagnostics; inspect command exit codes and tool errors before reporting success. Keep edits dependent on earlier results sequential.`;
+export function tool_guidance(options, tools) {
+    const selected = options.selectedTools ?? [
+        'read',
+        'bash',
+        'edit',
+        'write',
+    ];
+    const indirect = selected.includes('codemode') || selected.includes('tool_search');
+    const reachable = tools.filter((tool) => tool.exposure !== 'hidden' &&
+        (selected.includes(tool.name) ||
+            (indirect &&
+                ['codemode', 'deferred'].includes(tool.exposure))));
+    const names = reachable
+        .flatMap((tool) => [
+        tool.name,
+        tool.namespace?.name ?? '',
+        ...(tool.namespace?.aliases ?? []),
+    ])
+        .join('\n');
+    // Pi lists configured indirect servers before their background connections complete.
+    const servers = indirect
+        ? (options.sections?.mcp_servers ?? '')
+        : '';
+    const available = `${names}\n${servers}`.toLowerCase();
+    const shell = selected.some((name) => ['bash', 'powershell'].includes(name)) ||
+        reachable.some((tool) => ['bash', 'powershell'].includes(tool.name));
+    const editing = selected.some((name) => ['edit', 'write'].includes(name)) ||
+        reachable.some((tool) => ['edit', 'write'].includes(tool.name));
+    return [
+        shell ? NOPEEK_GUIDANCE : '',
+        shell && editing ? VALIDATION_GUIDANCE : '',
+        available.includes('omnisearch') ? OMNISEARCH_GUIDANCE : '',
+        available.includes('sqlite') ? SQLITE_GUIDANCE : '',
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
+export default function tool_guidance_extension(pi) {
+    pi.on('before_agent_start', (event) => {
+        const guidance = tool_guidance(event.systemPromptOptions, pi.getAllTools());
+        if (guidance)
+            event.systemPromptOptions.sections.my_pi_tool_guidance =
+                guidance;
+        else
+            delete event.systemPromptOptions.sections.my_pi_tool_guidance;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@spences10/pi-tool-guidance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Packaged nopeek, Omnisearch and SQLite workflow guidance for Pi",
+  "keywords": [
+    "pi",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/spences10/my-pi/tree/main/packages/pi-tool-guidance#readme",
+  "license": "MIT",
+  "author": "Scott Spence <me@scottspence.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spences10/my-pi.git",
+    "directory": "packages/pi-tool-guidance"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.0",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.4.0"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png",
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run build:self",
+    "build:self": "vp exec tsc -p tsconfig.build.json",
+    "check": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run check:self",
+    "check:self": "vp exec tsc --noEmit -p tsconfig.json",
+    "test": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run test:self",
+    "test:self": "vp test run",
+    "coverage:self": "vp test run --coverage",
+    "coverage": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run coverage:self"
+  }
 }

package/skills/my-pi-nopeek/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: my-pi-nopeek
+# prettier-ignore
+description: Use when loading .env credentials, running authenticated commands, or keeping secret values out of Pi context.
+compatibility: Requires Pi with shell access and the nopeek CLI.
+---
+
+# Credential-dependent commands
+
+Use the nopeek CLI to reduce accidental disclosure. This skill does
+not install hooks, load credentials automatically, or guarantee safe
+output.
+
+1. Inspect key names with `pnpx nopeek list` or `pnpx nopeek status`;
+   never read secret files into model context.
+2. In pnpm projects use `pnpx nopeek`; otherwise use `npx nopeek`.
+3. Prefer one-shot execution with an explicit key allowlist:
+
+   ```bash
+   pnpx nopeek run .env --only DATABASE_URL -- sh -c 'psql "$DATABASE_URL" -c "select 1"'
+   ```
+
+4. Keep variable expansion inside the child shell. Do not print keys,
+   run `env`/`printenv`, enable tracing, or place secret values in
+   arguments.
+5. Review what the child command prints: nopeek cannot prevent
+   arbitrary applications from leaking credentials through stdout or
+   stderr.
+6. Use `nopeek load` only with confirmed persistent harness injection,
+   or when loading and execution happen in the same trusted shell. A
+   source-file result does not persist into another Pi tool call.
+7. Use `pnpx nopeek audit` for exposure and gitignore checks.
+
+Pi's redaction extension is a separate best-effort safety net, not a
+security boundary. If secret output is unavoidable, stop and agree on
+a safer workflow rather than exposing it.
+
+The CLI must be available through the user's package runner or
+installed locally. Do not change their credential storage or
+configuration implicitly. See
+[nopeek's threat model](https://github.com/spences10/nopeek#threat-model-and-non-goals).

package/skills/my-pi-omnisearch/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: my-pi-omnisearch
+# prettier-ignore
+description: Use when researching current facts, verifying documentation, or finding sources with a configured Omnisearch MCP server.
+compatibility: Requires Pi with a configured Omnisearch MCP server.
+---
+
+# Verified web research
+
+This skill supplies guidance, not an MCP server or provider
+credentials. Use the user's configured integration; do not install or
+configure one without authorization.
+
+1. Discover the actual namespace and tool names. In codemode use
+   `searchTools("web search")`, `describeNamespace(namespace)`, and
+   `describeTool(name)`; use tool search when that is the available
+   route. Never assume hyphenated server names are valid JavaScript
+   identifiers.
+2. Use `web_search` for discovery. Choose providers deliberately:
+   Tavily for factual/cited searches, Brave or Kagi for operators, and
+   Exa for semantic discovery, when those providers are available.
+3. Use `web_extract` to read actual source content before making
+   claims. Search snippets alone are not verified evidence.
+4. Use `ai_search` when a synthesis with sources helps; verify
+   important claims against those sources.
+5. Prefer official documentation, repositories, release notes, and
+   source. State source conflicts, uncertainty, and partial tool
+   failures.
+6. In codemode inspect MCP `isError` results, not just promise
+   resolution.
+
+If the server is unavailable, say so and use an available research
+tool without claiming Omnisearch verified the result. Never invent
+sources.

package/skills/my-pi-sqlite/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: my-pi-sqlite
+# prettier-ignore
+description: Use when inspecting, querying, or modifying SQLite databases through a configured SQLite MCP server.
+compatibility: Requires Pi with a configured SQLite MCP server.
+---
+
+# SQLite workflow
+
+This skill does not install an MCP server, open databases
+automatically, or authorize writes. Keep the user's server
+configuration and permissions.
+
+1. Discover actual tool names with codemode `searchTools("SQLite")`,
+   `describeNamespace(namespace)`, and `describeTool(name)`, or tool
+   search.
+2. Use `open_database` for existing files. Use `create_database` only
+   when creating a database is explicitly intended.
+3. Inspect with `database_info`, `list_tables`, `describe_table`, or
+   `export_schema` before constructing queries.
+4. Use `execute_read_query` for SELECT, PRAGMA, and EXPLAIN. Keep
+   limits small, avoid selecting credential columns, and bound
+   model-visible output.
+5. Before authorized writes or schema changes, prefer
+   `backup_database` and an explicit transaction. Use
+   `execute_write_query` or `execute_schema_query` only when the
+   intent and affected data are clear.
+6. Commit only on success; roll back failed transactions. Close
+   databases with `close_database` when finished.
+7. In codemode inspect MCP `isError` results before continuing.
+
+Prefer MCP over raw sqlite3 or one-off Python SQL scripts. Use a shell
+fallback only when MCP is unavailable or the user explicitly requests
+it, and retain the same backup, transaction, and approval precautions.
+Never bypass MCP safety gates merely to make destructive SQL easier.