@stravica-ai/digital-operator-pa 0.1.42 → 0.1.43

package/dist/engineering-pa-core-extensions-atlassian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-core-extensions-atlassian",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Atlassian (Jira, Confluence, confluence-fetch) CLIs and library surface. Promoted into core for the alpha solo scaffold.",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-core-extensions-atlassian/src/confluence/client.mjs

@@ -9,6 +9,7 @@
 // Zero external dependencies - uses Node.js built-in fetch() and child_process.
 
 import { loadAtlassianCredentials } from '../common/secrets.mjs';
+import { readBody, formatHttpError } from '../jira/client.mjs';
 
 // ---- Exit-code-aware error ----------------------------------------------
 
@@ -145,33 +146,12 @@ export function createClient(options = {}) {
       // Parse response
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) {
-          data = await res.json();
-        } else {
-          const text = await res.text();
-          if (text) data = text;
-        }
+        data = await readBody(res);
       }
 
       // 4xx errors
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          if (Array.isArray(data.errors)) {
-            for (const e of data.errors) {
-              msgs.push(e.title || e.message || JSON.stringify(e));
-            }
-          } else {
-            for (const [field, msg] of Object.entries(data.errors)) {
-              msgs.push(`${field}: ${msg}`);
-            }
-          }
-        }
-        if (data && data.message) msgs.push(data.message);
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new ConfluenceError(`Confluence API error (${res.status}): ${detail}`, 2);
+        throw new ConfluenceError(formatHttpError('Confluence', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };

package/dist/engineering-pa-core-extensions-atlassian/src/jira/client.mjs

@@ -17,6 +17,71 @@ export class JiraError extends Error {
   }
 }
 
+// ---- Shared response parsing --------------------------------------------
+
+/**
+ * Read a fetch Response body without ever throwing on a bad body.
+ *
+ * Atlassian sometimes returns a non-JSON body (bare text, an HTML error
+ * page from Cloudflare, a proxy edge string) with a `Content-Type` that
+ * still says `application/json`, and a raw `res.json()` on that body throws
+ * `SyntaxError: Unexpected token 'C', "Client mus"... is not valid JSON`,
+ * which surfaces as an unhandled stack trace instead of an
+ * "authentication failed" message. Falls back to raw text on any parse
+ * failure and returns null for empty bodies.
+ *
+ * @param {Response} res
+ * @returns {Promise<any|string|null>}
+ */
+export async function readBody(res) {
+  const contentType = res.headers.get('Content-Type') || '';
+  const wantsJson = contentType.includes('application/json');
+  const raw = await res.text();
+  if (!raw) return null;
+  if (wantsJson) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw.trim();
+    }
+  }
+  return raw.trim();
+}
+
+/**
+ * Turn a parsed error body into a one-line, colleague-facing HTTP
+ * error message. `data` may be a parsed JSON object (Atlassian error
+ * shape), a plain string (non-JSON body), or null.
+ *
+ * @param {string} product   "Jira" or "Confluence"
+ * @param {number} status    HTTP status
+ * @param {any} data         Parsed body, string, or null
+ * @returns {string}
+ */
+export function formatHttpError(product, status, data) {
+  const parts = [];
+  if (data && typeof data === 'object') {
+    if (Array.isArray(data.errorMessages)) parts.push(...data.errorMessages);
+    if (data.errors) {
+      if (Array.isArray(data.errors)) {
+        for (const e of data.errors) {
+          parts.push(e.title || e.message || JSON.stringify(e));
+        }
+      } else if (typeof data.errors === 'object') {
+        for (const [field, msg] of Object.entries(data.errors)) {
+          parts.push(`${field}: ${msg}`);
+        }
+      }
+    }
+    if (data.message && parts.length === 0) parts.push(data.message);
+  } else if (typeof data === 'string' && data.length > 0) {
+    const trimmed = data.length > 120 ? `${data.slice(0, 120)}...` : data;
+    parts.push(trimmed);
+  }
+  const detail = parts.length > 0 ? parts.join('; ') : `HTTP ${status}`;
+  return `${product} API error (${status}): ${detail}`;
+}
+
 // ---- Credential loading -------------------------------------------------
 
 /**
@@ -142,26 +207,12 @@ export function createClient(options = {}) {
       // Parse response
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) {
-          data = await res.json();
-        } else {
-          const text = await res.text();
-          if (text) data = text;
-        }
+        data = await readBody(res);
       }
 
       // 4xx errors
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          for (const [field, msg] of Object.entries(data.errors)) {
-            msgs.push(`${field}: ${msg}`);
-          }
-        }
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new JiraError(`Jira API error (${res.status}): ${detail}`, 2);
+        throw new JiraError(formatHttpError('Jira', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };
@@ -309,19 +360,11 @@ export function createClient(options = {}) {
 
       let data = null;
       if (res.status !== 204) {
-        const contentType = res.headers.get('Content-Type') || '';
-        if (contentType.includes('application/json')) data = await res.json();
-        else { const text = await res.text(); if (text) data = text; }
+        data = await readBody(res);
       }
 
       if (res.status >= 400) {
-        const msgs = [];
-        if (data && data.errorMessages) msgs.push(...data.errorMessages);
-        if (data && data.errors) {
-          for (const [field, msg] of Object.entries(data.errors)) msgs.push(`${field}: ${msg}`);
-        }
-        const detail = msgs.length > 0 ? msgs.join('; ') : `HTTP ${res.status}`;
-        throw new JiraError(`Jira API error (${res.status}): ${detail}`, 2);
+        throw new JiraError(formatHttpError('Jira', res.status, data), 2);
       }
 
       return { status: res.status, data, headers: res.headers };

package/dist/engineering-pa-scaffold/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-scaffold",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "pa-init scaffolder + onboarding flows (solo, lead, member).",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-scaffold/src/commands/init.mjs

@@ -71,22 +71,24 @@ export async function runInit(options) {
     return 2;
   }
 
-  // Version-drift safety net (WSD-laptop cold install of 0.1.41). The
-  // scaffold pins an exact version and ships a `.npmrc` scope override,
-  // so pnpm should never resolve a different version — but if the guard
-  // ever misses, this prints one line naming the mismatch so a colleague
-  // can see it immediately instead of hitting a "Command X not found" on
-  // an older bin surface. Read from the SAME source `pa status` reads —
-  // the resolved package.json inside the instance's node_modules.
+  // Version-drift safety net (WSD-laptop cold install of 0.1.41, second-
+  // machine re-run of 0.1.42). The scaffold pins an exact version and
+  // ships a `pnpm-workspace.yaml` with `minimumReleaseAgeExclude` for
+  // this package, so pnpm should never resolve a different version, but
+  // if the guard ever misses, this prints one line naming the mismatch
+  // so a colleague can see it immediately instead of hitting a "Command
+  // X not found" on an older bin surface. Read from the SAME source
+  // `pa status` reads: the resolved package.json inside the instance's
+  // node_modules.
   const scaffoldedVersion = config.pkgVersion;
   const installedVersion = readInstalledDopVersion(config.targetDir);
   if (scaffoldedVersion && installedVersion && installedVersion !== scaffoldedVersion) {
     process.stderr.write(
-      `pa-init: WARNING — scaffold pinned @stravica-ai/digital-operator-pa@${scaffoldedVersion} `
+      `pa-init: WARNING - scaffold pinned @stravica-ai/digital-operator-pa@${scaffoldedVersion} `
       + `but pnpm resolved ${installedVersion}. This usually means pnpm's `
       + `minimumReleaseAge gate filtered the pinned version out; the shipped `
-      + `.npmrc scopes minimumReleaseAge=0 for @stravica-ai which normally cures it. `
-      + `Run \`pnpm install\` inside ${config.targetDir} again to reconcile.\n`,
+      + `pnpm-workspace.yaml excludes @stravica-ai/digital-operator-pa from the gate `
+      + `which normally cures it. Run \`pnpm install\` inside ${config.targetDir} again to reconcile.\n`,
     );
   }
 

package/dist/engineering-pa-scaffold/src/generator.mjs

@@ -327,32 +327,42 @@ export function buildGitignore() {
 }
 
 /**
- * Build the instance-level `.npmrc` contents.
+ * Build the instance-level `pnpm-workspace.yaml` contents.
  *
- * Overrides pnpm's default `minimumReleaseAge` (in effect since pnpm 10)
- * FOR THE `@stravica-ai` scope only. Rationale from the WSD-laptop cold
- * install of 0.1.41 (2026-09-16): pnpm's supply-chain gate silently
- * resolves a freshly-published tarball's caret range down to the previous
- * version — the instance ended up on 0.1.39 with no `jira` / `confluence`
- * / `confluence-fetch` bins, and the guide's Atlassian step failed with
- * "Command jira not found" on the very version the guide had just
- * installed. The scaffold already pins an EXACT dependency spec (see
- * `buildOperatorPackageJson` and `resolveInstalledDopVersion`), but an
- * exact spec can still be filtered out under `minimumReleaseAge`; the
- * scoped override belt-and-braces the pin so `pnpm install` inside the
- * scaffolded instance always resolves the version the pin names.
- * Non-`@stravica-ai` packages continue to honour the operator's own
- * `minimumReleaseAge` if they have one set globally.
+ * Excludes `@stravica-ai/digital-operator-pa` from pnpm's supply-chain
+ * age gate (`minimumReleaseAge`) BY NAME. Everything else the instance
+ * ever installs still honours whatever `minimumReleaseAge` the operator
+ * has set. The exclude ships instead of the older `.npmrc` line because
+ * pnpm reads `minimumReleaseAge` / `minimumReleaseAgeExclude` from
+ * `pnpm-workspace.yaml` only; `.npmrc` is not honoured for these
+ * settings (empirically verified on pnpm 10.32 against the live
+ * registry: `.npmrc @stravica-ai:minimumReleaseAge=0` did not defeat a
+ * `minimumReleaseAge=10080` set at the same scope; a
+ * `pnpm-workspace.yaml` with `minimumReleaseAgeExclude: [<pkg>]` did).
+ *
+ * Rationale from the second-machine re-run of 0.1.42 (2026-09-16): the
+ * `.npmrc` override written into the instance was a no-op, so the
+ * belt-and-brace promised alongside the exact pin never bit. This file
+ * is the real belt-and-brace: `pnpm install` inside the instance always
+ * resolves the pinned version even when the operator's pnpm carries a
+ * non-zero `minimumReleaseAge` (pnpm 11 ships one by default).
+ *
+ * The file also marks the instance as its own pnpm workspace root,
+ * which is fine: instances never nest inside another pnpm workspace
+ * (the onboarding guide's warning covers the reverse direction).
  */
-export function buildInstanceNpmrc() {
+export function buildInstanceWorkspaceYaml() {
   return [
-    '# @stravica-ai scope override for pnpm supply-chain gating.',
-    '# pa-init pins an exact @stravica-ai/digital-operator-pa version in package.json.',
-    '# pnpm\'s default minimumReleaseAge can otherwise filter a freshly-published',
-    '# tarball out of resolution and drop the instance onto a previous version',
-    '# with a different bin surface (WSD-laptop cold-install regression, 0.1.41).',
+    '# @stravica-ai/digital-operator-pa exclusion for pnpm supply-chain gating.',
+    '# pa-init pins the exact @stravica-ai/digital-operator-pa version in package.json,',
+    '# but pnpm\'s minimumReleaseAge (default 0 on pnpm 10, non-zero on some 11 defaults)',
+    '# can still filter that pin out during `pnpm install` and drop the instance onto a',
+    '# previous version with a different bin surface (WSD-laptop cold-install regression,',
+    '# 0.1.41 / 0.1.42). pnpm reads minimumReleaseAge only from pnpm-workspace.yaml, so',
+    '# the exclusion has to live here rather than in .npmrc.',
     '# Non-@stravica-ai packages still honour any minimumReleaseAge set globally.',
-    '@stravica-ai:minimumReleaseAge=0',
+    'minimumReleaseAgeExclude:',
+    '  - "@stravica-ai/digital-operator-pa"',
     '',
   ].join('\n');
 }
@@ -655,7 +665,7 @@ export function buildPlanFromTemplates(config, templates) {
   plan.push({ kind: 'json', path: 'package.json', contents: pkg });
   plan.push({ kind: 'file', path: '.gitignore', contents: gitignore });
   plan.push({ kind: 'file', path: '.nvmrc', contents: '24\n' });
-  plan.push({ kind: 'file', path: '.npmrc', contents: buildInstanceNpmrc() });
+  plan.push({ kind: 'file', path: 'pnpm-workspace.yaml', contents: buildInstanceWorkspaceYaml() });
 
   plan.push({ kind: 'json', path: '.claude/settings.json', contents: buildClaudeSettingsJson() });
   // /research slash command: rendered from the packaged core doc so the

package/docs/onboarding-solo.md

@@ -21,11 +21,25 @@ Linux and WSL are equivalent. Install Node 24 through your platform's normal cha
 
 ```sh
 mkdir ~/pa-bootstrap && cd ~/pa-bootstrap
-# pnpm 11.14 rejects the `devEngines.packageManager` line `pnpm init -y` writes,
-# and `-y` is silently ignored, so write a minimal package.json directly:
+# Two files, one heredoc each. `pnpm init -y` writes a `devEngines.packageManager`
+# line pnpm 11.14 then rejects, and `-y` is silently ignored, so write a minimal
+# package.json directly. The `pnpm-workspace.yaml` is the load-bearing file:
+# pnpm holds packages published in the last week back by default (the
+# `minimumReleaseAge` supply-chain gate; it defaults to 0 on pnpm 10 and to a
+# non-zero window on some pnpm 11 defaults), and this repo releases often, so
+# without an explicit exclude an unversioned `pnpm add` silently resolves down
+# to a previous version with a different bin surface. pnpm reads
+# `minimumReleaseAge*` settings ONLY from `pnpm-workspace.yaml` (not from
+# `.npmrc`), and the exclude below trusts only this one package by name so
+# every other dependency your bootstrap ever pulls still honours the operator's
+# global gate.
 cat > package.json <<'JSON'
 { "name": "pa-bootstrap", "private": true }
 JSON
+cat > pnpm-workspace.yaml <<'YAML'
+minimumReleaseAgeExclude:
+  - "@stravica-ai/digital-operator-pa"
+YAML
 pnpm add @stravica-ai/digital-operator-pa
 pnpm exec pa-init --mode=solo --name=<pa-name> --operator=<your-name> \
   --target=$HOME/<pa-name>-instance --non-interactive
@@ -37,11 +51,13 @@ git add -A && git commit -m "scaffold"
 
 Pick a `<pa-name>` in lowercase kebab-case (`alex`, `sam`, `hal-9000`). It becomes the agent directory (`agents/<pa-name>/`) and shows up in every log line.
 
-`pa-init` writes the instance's `package.json` with an EXACT `@stravica-ai/digital-operator-pa` dependency (the version it just installed into `pa-bootstrap`, not a caret range) and drops an `.npmrc` in the instance with `@stravica-ai:minimumReleaseAge=0`. Both belt-and-brace pnpm's supply-chain gate: without them a freshly-published tarball can silently resolve down to the previous version, which may ship a different bin surface.
+`pa-init` writes the instance's `package.json` with an EXACT `@stravica-ai/digital-operator-pa` dependency (the version it just installed into `pa-bootstrap`, not a caret range) and drops a `pnpm-workspace.yaml` inside the instance that excludes `@stravica-ai/digital-operator-pa` from the same age gate. Together they belt-and-brace pnpm's supply-chain gate: without them a freshly-published tarball can silently resolve down to the previous version, which may ship a different bin surface.
+
+**Sanity check the version.** `pa-init` prints `package: @stravica-ai/digital-operator-pa@<version>` right after the target line. If the version you see is older than the one `npm view @stravica-ai/digital-operator-pa version` reports, the exclude in your bootstrap `pnpm-workspace.yaml` did not take (rare; usually a stale pnpm store or a typo in the yaml). The `@latest` tag does NOT bypass the release-age gate, so the recovery is to pin the version npm names: `pnpm add @stravica-ai/digital-operator-pa@<version npm view prints>` inside the bootstrap dir, then re-run `pa-init`. When pnpm 11 sees a pinned version that would otherwise be gated, it adds an entry of its own to `pnpm-workspace.yaml` under `minimumReleaseAgeExclude`; the file the guide already asked you to write covers that write.
 
 `pnpm install` in the instance runs automatically as the last step of `pa-init` (skip it with `--skip-install` for CI). The `pa status` verification also runs at the end and prints the resolved package version; a mismatch between the scaffold pin and the installed version prints a WARNING line naming both, so a broken guard surfaces immediately instead of hiding behind a "Command not found" later.
 
-**Do not put the instance under a directory that already contains a `pnpm-workspace.yaml`.** pnpm treats the instance as a workspace member, `pnpm install` silently no-ops, and `node_modules/.bin/pa` never appears. Keep `--target` outside any pnpm workspace root (a top-level `$HOME/<pa-name>-instance` as shown above is safe).
+**Do not put the instance under a directory that already contains a `pnpm-workspace.yaml`.** pnpm treats the instance as a workspace member, `pnpm install` silently no-ops, and `node_modules/.bin/pa` never appears. Keep `--target` outside any pnpm workspace root (a top-level `$HOME/<pa-name>-instance`, as shown above, is safe; `~/pa-bootstrap` itself is such a workspace root now, so never nest the `--target` inside it).
 
 ## 2. Sanity-check the install
 
@@ -136,6 +152,8 @@ pnpm exec secrets set JIRA_API_TOKEN <paste-token>       # id.atlassian.com/mana
 
 `secrets set` self-initialises the vault (age keypair, `.vault/recipients.txt`, empty encrypted store) on the first write when there is nothing at `.vault/` yet. It prints a one-line notice on stderr saying so and continues. You do not need to run `secrets init` manually first. Every `secrets set` also prints one stderr line naming which vault it wrote to; on a fresh solo install with no scope configured that says the write went to the `(legacy)` pot (no scope specified, no default configured). Informational, safe to ignore. Set `SECRETS_DEFAULT_SCOPE` in your environment or configure `defaultScope` in `~/.config/stravica-pa/defaults.json` if you want a named scope; solo mode does not require one.
 
+The age key that self-init generates lives at `~/.config/stravica-pa/age-key.txt` (one per laptop, not per instance). If that file already exists when you scaffold a second PA on the same machine, self-init reuses it, so both instances read and write the same encrypted vault content when a `.vault/` sits under both. That is the point: a single key per operator per machine. To force a fresh key, move the existing one aside (`mv ~/.config/stravica-pa/age-key.txt ~/.config/stravica-pa/age-key.txt.prev`) before the first `secrets set` in the new instance; the vault contents in the old instance will then be unreadable to the new key.
+
 Verify with `pnpm exec jira auth` and `pnpm exec confluence auth`; each prints the current user on success. Credentials also resolve from environment variables of the same names, so a `.env` or shell profile works as an alternative to `secrets`. The `atlassian` entry in `operator/extensions/manifest.json` records the extension is enabled and repeats the setup line.
 
 `jira mine` returns your open issues across every project the account can see. If you spend most of your Jira time in one project, set `JIRA_DEFAULT_PROJECT` (env var or a vault key of the same name) and `jira mine` narrows to it unless you pass `--project KEY` or `--all`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",