vouchington-tooling 0.3.2 → 0.3.4

package/README.md

@@ -89,6 +89,8 @@ as not merged to main, and a missing base is unavailable.
 
 Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
 need `agent-blackboard@^0.3.1`. Snapshot cleanup accepts only package-generated temporary paths.
+Programmatic callers launched from a different workspace directory pass their own module URL as
+`dependencies: { resolveFrom: import.meta.url }`; the CLI defaults to the current package context.
 It captures a target under a private tombstone, validates partition names, permissions, JSONL,
 ordering, terminal manifests, and the identity-bound cleanup receipt before deleting files, and
 restores the original path on a validation failure. Once deletion begins, it retains a private

package/dist/agent-blackboard/index.d.mts

@@ -24,6 +24,7 @@ export type BlackboardClientModule = {
 type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
 export type BlackboardClientDependencies = {
     loadClient?: BlackboardClientLoader;
+    resolveFrom?: string | URL;
 };
 export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
 export declare function probeBlackboard(env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<void>;

package/dist/agent-blackboard/index.mjs

@@ -1,4 +1,15 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { assertSessionId } from './session-id.mjs';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mjs';
 export { assertSessionId } from './session-id.mjs';
@@ -12,7 +23,7 @@ export function resolveBlackboardConnection(env = process.env) {
     return { baseUrl, token, readRetry: {} };
 }
 export async function probeBlackboard(env, dependencies) {
-    const { Sessions } = await loadClient(dependencies?.loadClient);
+    const { Sessions } = await loadClient(dependencies);
     await new Sessions(resolveBlackboardConnection(env)).list({ limit: 1 });
 }
 export async function appendJournal(input) {
@@ -32,7 +43,7 @@ export async function appendJournal(input) {
     if (!markdown)
         throw new Error(`note file is empty: ${input.markdownFile}`);
     const connection = resolveBlackboardConnection(input.env);
-    const { Sessions, Entries } = await loadClient(input.dependencies?.loadClient);
+    const { Sessions, Entries } = await loadClient(input.dependencies);
     await new Sessions(connection).ensure({
         id: input.sessionId,
         parentSessionId: input.parentSessionId ?? null,
@@ -47,7 +58,7 @@ export async function appendJournal(input) {
 }
 export async function readJournal(sessionId, env, dependencies) {
     assertSessionId(sessionId);
-    const { Entries } = await loadClient(dependencies?.loadClient);
+    const { Entries } = await loadClient(dependencies);
     const entries = [];
     for await (const entry of new Entries(resolveBlackboardConnection(env)).get({
         sessionId,
@@ -79,16 +90,24 @@ export function formatJournalEntries(sessionId, entries) {
         .map(({ createdAt, markdown }) => `## ${createdAt}\n\n${markdown}`)
         .join('\n\n');
 }
-async function loadClient(loader = defaultClientLoader) {
+async function loadClient(dependencies = {}) {
+    const loader = dependencies.loadClient ?? (() => defaultClientLoader(dependencies.resolveFrom));
     try {
         return await loader();
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND')
-            throw new Error('agent-blackboard is not installed; install the optional agent-blackboard peer dependency', { cause: error });
+        if (isMissingModuleError(error))
+            throw new Error('agent-blackboard is not installed; install it alongside vouchington-tooling to use this integration', { cause: error });
         throw error;
     }
 }
-async function defaultClientLoader() {
-    return (await import('agent-blackboard'));
+async function defaultClientLoader(resolveFrom) {
+    const consumerRequire = createRequire(resolveFrom ?? resolve(process.cwd(), 'package.json'));
+    const specifier = pathToFileURL(consumerRequire.resolve('agent-blackboard')).href;
+    return (await import(__rewriteRelativeImportExtension(specifier)));
+}
+function isMissingModuleError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND'));
 }

package/dist/gha-post-review/github.mjs

@@ -33,7 +33,7 @@ export function writePostedOutput(posted, outputPath = process.env.GITHUB_OUTPUT
         return;
     appendFileSync(outputPath, `posted=${posted ? 'true' : 'false'}\n`);
 }
-function readPullRefs(repository, prNumber, exec) {
+function readPullState(repository, prNumber, exec) {
     let lastError;
     for (let attempt = 1; attempt <= 3; attempt += 1) {
         try {
@@ -41,7 +41,7 @@ function readPullRefs(repository, prNumber, exec) {
                 'api',
                 `repos/${repository}/pulls/${prNumber}`,
                 '--jq',
-                '[.head.sha, .base.sha] | @tsv',
+                '[.head.sha, .base.sha, .draft, .state] | @tsv',
             ]).split('\t');
         }
         catch (error) {
@@ -72,14 +72,20 @@ export function createGhPostReviewIo(options) {
             if (expectedBaseSha && !/^[0-9a-f]{40}$/u.test(expectedBaseSha)) {
                 throw new ReviewPayloadError('EXPECTED_BASE_SHA must be a full lowercase commit SHA.');
             }
-            const refs = readPullRefs(repository, prNumber, exec);
-            const [headSha = '', baseSha = ''] = refs;
+            const state = readPullState(repository, prNumber, exec);
+            const [headSha = '', baseSha = '', draft = '', pullState = ''] = state;
             if (!/^[0-9a-f]{40}$/u.test(headSha)) {
                 throw new ReviewPayloadError(`Could not resolve PR head SHA (got "${headSha}").`);
             }
             if (!/^[0-9a-f]{40}$/u.test(baseSha)) {
                 throw new ReviewPayloadError(`Could not resolve PR base SHA (got "${baseSha}").`);
             }
+            if (draft !== 'false') {
+                throw new ReviewPayloadError('Pull request became a draft before posting the review.');
+            }
+            if (pullState !== 'open') {
+                throw new ReviewPayloadError('Pull request closed before posting the review.');
+            }
             if (expectedHeadSha && headSha !== expectedHeadSha) {
                 throw new ReviewPayloadError('PR head changed before posting the selected review.');
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -252,14 +252,6 @@
     "@types/picomatch": "^4.0.3",
     "agent-blackboard": "^0.3.1"
   },
-  "peerDependencies": {
-    "agent-blackboard": "^0.3.1"
-  },
-  "peerDependenciesMeta": {
-    "agent-blackboard": {
-      "optional": true
-    }
-  },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"
   },

package/skills/github-actions-checklist/SKILL.md

@@ -8,13 +8,43 @@ description: Use when editing GitHub Actions workflows or composite actions to k
 Use before editing a workflow or composite action. Repository-local instructions own runners,
 approved action pinning, concurrency naming, secrets, permissions, and workflow-only PR rules.
 
+Apply this portable baseline unless a stricter repository-local rule overrides it:
+
+- Use `pull_request` for pull-request workflows in private repositories. Reserve
+  `pull_request_target` for base-owned orchestration in public repositories or narrowly scoped
+  Dependabot/Renovate automation. A privileged workflow must never check out or execute untrusted
+  pull-request content.
+- Load [github-actions-authoring](../github-actions-authoring/SKILL.md) when changing orchestration.
+  Do not poll remote workflow, deployment, lease, service, or health state.
+- Give every concrete job a timeout of no more than 30 minutes. A caller job that invokes a reusable
+  workflow through top-level `jobs.<job_id>.uses` cannot accept `timeout-minutes`; enforce the bound
+  on every concrete job inside the called workflow. If the underlying operation cannot terminate
+  inside that bound, decompose it into event-driven phases; lowering or moving the timeout alone does
+  not fix the design. Preserve a required job or check name with a bounded fan-in job when splitting
+  work would otherwise change the repository's merge contract. Each underlying phase must also have
+  a deadline of no more than 30 minutes and support cancellation, rollback, or an explicit terminal
+  retained/recovery state. An event callback may report completion; it must not hide a longer-running
+  operation in another service.
+- Use GitHub-hosted runners only for public repositories. Private repositories use the consumer's
+  approved self-hosted or disposable runner labels.
+- Pin every repository-backed external `uses:` reference—anything other than a local `./...`
+  action—to a full lowercase 40-character Git SHA followed immediately by its machine-maintainable
+  version comment, such as `# v4.2.0`, so Dependabot can update both. Pin `docker://...` actions to an
+  immutable `@sha256:` image digest instead of a Git SHA. Keep GitHub Actions dependency updates
+  enabled.
+- Workflow tests and fixtures must not assert an action dependency's exact SHA or version. Assert
+  the action identity and Git SHA shape, or derive the dependency ref from the workflow under test,
+  so dependency-update pull requests can change pins without synchronized fixture edits. This does
+  not prohibit asserting an exact source revision in `with.ref` when exact-head checkout is a
+  workflow security invariant.
+
 1. Read every applicable `AGENTS.md` and `CLAUDE.md` from the repository root through the workflow,
    plus relevant CI documentation and callers. Apply the closest instruction only when rules
    conflict. Identify trusted and untrusted inputs and every credential boundary.
 2. Give each job the least permissions it needs. Keep untrusted pull-request content out of shell
    interpolation, privileged tokens, and write-capable steps.
-3. Use the repository's pinned-action and runner policy. Keep checkout refs, artifact boundaries,
-   caches, and concurrency behavior explicit.
+3. Apply the portable pinning, runner, trigger, and timeout baseline plus any stricter consumer
+   policy. Keep checkout refs, artifact boundaries, caches, and concurrency behavior explicit.
 4. Validate changed YAML with the local workflow checker and run the affected workflow tests or
    scripts. Update local CI documentation when behavior or operator expectations change.
 5. Review the final diff for privilege escalation, accidental secret exposure, unsafe quoting,

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "agent-workflow/SKILL.md"
     },
     {
@@ -17,7 +17,7 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "blackboard/SKILL.md"
     },
     {
@@ -29,26 +29,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -58,22 +58,28 @@
       "path": "nextjs-vitest-test-authoring/SKILL.md",
       "prerequisites": ["vitest-test-authoring"]
     },
+    {
+      "name": "npm-publishing",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.5.1",
+      "path": "npm-publishing/SKILL.md"
+    },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "organize-github-issues/SKILL.md"
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "planning/SKILL.md"
     },
     {
@@ -97,43 +103,43 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "retrospective-distill/SKILL.md"
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "review-ci-logs/SKILL.md"
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "review-github-issue-taxonomy/SKILL.md"
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "revisit-followups/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.1",
       "path": "static-analysis-checklist/SKILL.md"
     },
     {

package/skills/npm-publishing/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: npm-publishing
+description: Bootstrap an npm package and give a human the exact commands to publish it publicly and configure GitHub trusted publishing.
+---
+
+# npm publishing bootstrap
+
+Prepare the local package, but leave public registry and trusted-publisher mutations to the human.
+Read every applicable `AGENTS.md` and `CLAUDE.md` from the repository root through the package.
+Repository-local policy and the consumer wrapper own the package path and name, npm scope, GitHub
+repository, release workflow, build commands, and whether a laptop may publish.
+
+## Prepare the package
+
+1. Resolve the absolute repository root, package directory relative to that root, exact npm package
+   name, `owner/repository`, and release workflow filename. The workflow value is the case-sensitive
+   filename under `.github/workflows`, not a path. Do not leave placeholders in the final commands.
+2. Confirm npm 11.15 or newer, account-level two-factor authentication, and write access to the npm
+   package or scope. Inspect the workflow on the repository's default branch: it must grant
+   `id-token: write`, use a supported runner, install a trusted-publishing-capable npm version, and
+   publish this package.
+3. When the package does not exist in the registry, create the smallest useful stub module in its
+   intended directory. Follow neighboring package conventions for metadata, source, exports, types,
+   license, README, build output, and workspace registration. Do not replace an existing module with
+   a stub or publish a version already present in the registry.
+4. Build the package as required, then inspect the publication lifecycle and exact payload with
+   `npm publish <package-directory> --access public --dry-run`. Stop if it includes secrets,
+   environment files, source maps, unrelated workspace files, or missing runtime/type entrypoints.
+   This dry run must include `prepublishOnly`; a pack-only check is insufficient when that lifecycle
+   script can change the payload.
+5. If the package already exists, have the human run `npm trust list <package-name>` before any
+   mutation. Omit the initial publish command. If a trust relationship already exists, report it and
+   omit the trust-creation command rather than revoking or replacing it.
+
+## Hand off the mutations
+
+Do not run a real `npm publish` or a mutating `npm trust` subcommand. Explain that the first command
+creates an externally visible, effectively irreversible package version and the second grants the
+named workflow publish authority. Include the publish command only when bootstrapping a package that
+does not exist; an existing package proceeds directly to trust setup when its trust list is empty.
+Tell the human to append a current one-time password after each final `--otp=` without sharing or
+recording it. Warn that the requested `--otp=` form can expose the OTP in shell history and process
+arguments, and tell the human to follow their local secret-handling policy. Give the applicable
+commands with fully resolved values and in this order:
+
+```sh
+cd /absolute/repository/root
+npm publish ./relative/package-directory --access public --otp=
+npm trust github @scope/package \
+  --repo owner/repository \
+  --file release.yml \
+  --allow-publish \
+  --yes \
+  --otp=
+```
+
+The `cd` target must be the directory from which the relative publish path resolves. If local policy
+prohibits publishing from the current machine, say so and identify the approved environment while
+preserving the same ordered commands. Ask the human to confirm the package payload, package name,
+repository, workflow filename, and publish permission immediately before running them.
+
+Afterward, have the human verify any newly published package version and run
+`npm trust list @scope/package` again. Do not retry authorization or registry failures blindly, and do
+not fall back to a long-lived npm token without explicit direction.