@stravica-ai/digital-operator-pa 0.1.40 → 0.1.41

package/README.md

@@ -20,6 +20,11 @@ New to the platform and setting up a single-person PA on one laptop? Follow
 ten-minute walkthrough from an empty directory to a working PA under your
 own Claude Code subscription.
 
+Want a plain-language tour of what the PA does before you install it? Read
+[`./docs/what-it-can-do.md`](./docs/what-it-can-do.md) — a day-to-day view
+of the capabilities, how it learns you, and what is (and is not) in this
+release.
+
 ## Bins
 
 The wrapper exposes the platform's operator-facing CLIs:

package/bin/confluence

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// confluence - Confluence Cloud CLI (v1 CQL + v2 CRUD). Shares JIRA_* creds.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/confluence/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[confluence] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

package/bin/confluence-fetch

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// confluence-fetch - search + fetch + save Confluence pages into operator/notes/.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/confluence-fetch/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[confluence-fetch] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

package/bin/jira

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// jira - Jira REST v3 CLI. Auth reads env vars first, else `secrets get JIRA_*`.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-core-extensions-atlassian sources.
+import('../dist/engineering-pa-core-extensions-atlassian/src/jira/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).catch((err) => {
+  process.stderr.write(`[jira] ${err?.message ?? err}\n`);
+  process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+});

package/dist/engineering-pa-core/knowledge/platform-tooling/workspace-extensions.md

@@ -0,0 +1,62 @@
+<!--
+  scaffold: workspace-extensions.md
+  bucket: platform-tooling (Bucket 7)
+  audience: the PA, deciding when to propose that the operator build a workspace page.
+  what belongs here:
+    - placement rule (common-use CLIs in core, personal pages as extensions).
+    - triggers the PA watches for.
+    - what to offer, and what NOT to prompt for.
+    - how to prompt.
+    - cross-link to the workspace README for the mechanism.
+-->
+
+# Workspace extensions: when to propose one
+
+## Placement rule
+
+Common-use CLIs live in core. Personal workspace pages are a more personal expression of how the operator works, so they belong in an extension. The PA carries the knowledge that decides when to prompt the operator to build one.
+
+The mechanism itself is already live. Static page overlay under `operator/extensions/workspace/<name>.html`, optional API routes via `operator/extensions/workspace/api.mjs` (exporting `register(addRoute)`), nav registration via `operator/extensions/workspace/nav.json` (or team-scoped `nav.<team>.json` fragments). Full detail: `@stravica-ai/engineering-pa-workspace/README.md` (extension mechanism section).
+
+## Triggers
+
+Three shapes of operator behaviour that mean a workspace page would pay for itself.
+
+1. **Repeated manual view.** The operator opens the same files, runs the same query, or screenshots the same panel more than twice in a week. The manual view is already a page; it just does not exist yet.
+2. **Explicit ask for a dashboard or "one page to see X".** Any request framed as "I want to see all my X in one place", "give me a page for Y", "I want to check Z at a glance". The operator has done the design work already.
+3. **An operator-installed tool with a natural page.** A Jira CLI plus a "my Jira today" habit is the archetype. Any tool the operator installed and now reaches for daily has a page shape latent in it.
+
+## What to offer
+
+Match the surface to the shape.
+
+- **Read-only view of files or state on disk.** Static page overlay. HTML file at `operator/extensions/workspace/<name>.html` served in place of a core same-named page, or as a new page at `/<name>.html`.
+- **Anything that needs server access or a write.** Static page plus an API route in `operator/extensions/workspace/api.mjs`. The route hangs off `register(addRoute)` and lands under `/__api/<name>/<verb>`.
+- **Discoverability in the sidebar.** Add a `nav.json` entry naming the page. If the operator runs multiple teams on the same box, use `nav.<team>.json` fragments so each team's entries survive the library merge.
+
+## What NOT to prompt for
+
+Not every operator habit is a workspace page.
+
+- **One-shot views.** A page for a single question the operator asked once is over-engineering. The answer belongs in the chat, or in a `viewer.html?file=...` link.
+- **Throwaway reports.** If the output has a shelf-life of one day, a workspace page is the wrong home. Stage the file, link it, move on.
+- **Anything that is a workspace page and a knowledge doc and a scheduled task rolled into one.** That is a tool. Propose `tool-developer` under Bucket 7 rule 9, not a workspace extension.
+
+## How to prompt
+
+One sentence. Name the page, the source of data, and the interaction shape.
+
+> "Want me to build a workspace page for X? Reads from Y, refresh on nav-load, no writes."
+
+Get an explicit yes before doing anything durable. On approval, either:
+
+- Invoke `pa-init workspace-extension <name>` for the file skeleton plus nav entry (add `--with-api` if the page needs a server route), then dispatch `tool-developer` for the real page content and any handler logic, OR
+- Skip the scaffold verb and dispatch `tool-developer` directly if the shape is unusual enough that the skeleton would just be deleted.
+
+The scaffold verb is a thirty-second cost saver; it does not replace the design conversation.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 9 (proactive tool proposal): the parent rule; workspace pages count as a tool for that rule.
+- `@stravica-ai/engineering-pa-workspace/README.md`: the extension mechanism, page overlay, API-route registration, nav merge, team scoping.
+- `packages/core/knowledge/platform-tooling/workspace-server.md`: workspace server operations (start, stop, viewer.html).

package/dist/engineering-pa-core-extensions-atlassian/README.md

@@ -1,31 +1,96 @@
 # @stravica-ai/engineering-pa-core-extensions-atlassian
 
-Identity: `@stravica-ai/engineering-pa-core-extensions-atlassian` — optional Atlassian (Jira/Confluence) core extension.
+Atlassian (Jira, Confluence) CLIs and library surface, promoted into core
+for the alpha solo scaffold. Common-use tools ship with the platform; the
+personal workspace pages colleagues build on top ship as extensions.
 
-## Status
+## Bins
 
-**Skeleton — v0.1.0.** Workspace-internal, `"private": true`, not individually published.
+Wrapped by `@stravica-ai/digital-operator-pa` and installed on `PATH` when
+that package is installed:
 
-Phase 2 promotes the existing operator-side Atlassian extension(s) into core via the extension-promotion mechanism: the upgrade tool detects a local extension matching this namespace, deactivates the local copy, copies operator-specific config across, and enables the core version.
+- `jira` - Jira REST v3 CLI. Verbs: `auth`, `mine`, `search`, `issue`,
+  `create`, `update`, `attach`, `transition`, `advance`, `cancel`,
+  `comment`, `worklog`, `projects`, `boards`, `sprint`, `link`,
+  `sync-statuses`, `bulk-transition`, `test`.
+- `confluence` - Confluence Cloud CLI (v1 CQL search, v2 page CRUD).
+  Verbs: `auth`, `spaces`, `pages`, `page`, `search`, `create`, `update`,
+  `comment`, `label`, `tree`, `recent`, `mine`, `mirror-folder`,
+  `mirror-page`, `test`.
+- `confluence-fetch` - convenience wrapper: search + fetch + save a page
+  to `operator/notes/` and open the workspace viewer.
 
-For v0.1.0, this is an empty slot so the manifest-toggleable extension model is established from day one.
+Run `jira --help`, `confluence --help`, `confluence-fetch --help` for the
+full verb list; each verb has its own `--help`.
 
-## Layout
+## Auth
+
+Both CLIs read three credentials from the environment first, else from the
+platform `secrets` bin. The keys are shared because Jira and Confluence
+target the same Atlassian site:
+
+- `JIRA_DOMAIN` - subdomain of `atlassian.net` (`foo` for `foo.atlassian.net`)
+- `JIRA_EMAIL` - your Atlassian account email
+- `JIRA_API_TOKEN` - a token from `https://id.atlassian.com/manage-profile/security/api-tokens`
+
+Two-step colleague setup, after installing `@stravica-ai/digital-operator-pa`:
 
 ```
-packages/core-extensions/atlassian/
-  index.mjs            # placeholder export
-  package.json         # name, version, scripts
-  README.md            # this file
-  test/index.test.mjs
+secrets set JIRA_DOMAIN yoursite
+secrets set JIRA_EMAIL   you@example.com
+secrets set JIRA_API_TOKEN <paste-token>
+```
+
+Resolution order for each key:
+
+1. Environment variable of the same name (`JIRA_DOMAIN`, ...).
+2. `secrets get <prefix>JIRA_DOMAIN` (etc.), where `<prefix>` comes from
+   `ATLASSIAN_SECRETS_PREFIX` (e.g. an org slug like `acme/` picks the `acme` vault scope in
+   an operator estate; empty by default so a solo colleague's single scope
+   just works).
+
+The tool never prints or logs the values; child-process reads use
+`stdio: ['ignore', 'pipe', 'pipe']`.
+
+## Configuration
+
+- `config/jira-workflow-chains.default.json` - shipped empty. `jira advance
+  <KEY> <STATUS>` walks a per-site chain of statuses; override by writing
+  `operator/config/jira-workflow-chains.json` in your workspace root.
+- `operator/config/jira-status-mappings.json` - per-project status mapping
+  used by `jira sync-statuses`; not shipped by default.
+- `JIRA_DEFAULT_PROJECT` (optional, env or vault key of the same name) -
+  when set, `jira mine` narrows to that project unless `--project KEY`
+  or `--all` is passed. With nothing configured, `jira mine` returns
+  issues across every project the account can see.
+
+## Library surface
+
+```js
+import {
+  createJiraClient,
+  createConfluenceClient,
+  storageToMarkdown,
+} from '@stravica-ai/digital-operator-pa/dist/engineering-pa-core-extensions-atlassian/index.mjs';
+
+const jira = createJiraClient();
+const { data } = await jira.get('/rest/api/3/myself');
 ```
 
-## Tests
+For tests, inject a stub credential resolver rather than the vault:
 
-```bash
-pnpm --filter @stravica-ai/engineering-pa-core-extensions-atlassian test
+```js
+const client = createJiraClient({
+  domain: 'yoursite',
+  email:  'you@example.com',
+  apiToken: 'test-token',
+  fetchFn: mockFetch,
+});
 ```
 
-## Standards
+## Workspace hook
 
-Follows the [tooling standard](../../../CONTRIBUTING.md#standards): JS only, zero npm deps, `node:test`, camelCase JSON.
+`jira` writes POST to `http://127.0.0.1:<workspacePort>/__api/jira/invalidate`
+after mutating verbs, so a workspace page can refresh cached data on
+change. The endpoint is a workspace-extension concern; the CLI treats a
+timeout or refused connection as fine (the write succeeded regardless).

package/dist/engineering-pa-core-extensions-atlassian/bin/confluence

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/confluence/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/bin/confluence-fetch

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/confluence-fetch/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/bin/jira

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/jira/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core-extensions-atlassian/config/jira-workflow-chains.default.json

@@ -0,0 +1,4 @@
+{
+  "_note": "Per-site Jira workflow chains for `jira advance <KEY> <STATUS>`. Ships empty because every Atlassian instance has its own workflows. Override by writing operator/config/jira-workflow-chains.json in your workspace root; the CLI reads that path first and falls back to this shipped default.",
+  "chains": []
+}

package/dist/engineering-pa-core-extensions-atlassian/index.mjs

@@ -1,9 +1,20 @@
-// @stravica-ai/engineering-pa-core-extensions-atlassian — optional Atlassian
-// integration (Jira/Confluence tooling + workspace pages).
+// @stravica-ai/engineering-pa-core-extensions-atlassian
 //
-// Status: skeleton. Phase 2 promotes the existing operator-side Atlassian
-// extension(s) into core. Until then, this is a placeholder slot so the
-// manifest-toggleable extension model is established from day one.
+// Common-use Atlassian CLIs (jira, confluence, confluence-fetch), promoted
+// into core so the alpha solo scaffold ships them out of the box. The bins
+// live under bin/ and are wrapped from @stravica-ai/digital-operator-pa's
+// bin map. Auth reads env vars first, else `secrets get JIRA_*` (see
+// src/common/secrets.mjs).
+
+export { createClient as createJiraClient, getCredentials as getJiraCredentials, JiraError } from './src/jira/client.mjs';
+export { createClient as createConfluenceClient, getCredentials as getConfluenceCredentials, ConfluenceError } from './src/confluence/client.mjs';
+export {
+  storageToMarkdown,
+  markdownToStorage,
+  storageToText,
+  textToStorage,
+} from './src/confluence/storage.mjs';
+export { loadAtlassianCredentials, resolveSecret, CredentialResolutionError } from './src/common/secrets.mjs';
 
 export const name = './';
-export const status = 'skeleton';
+export const status = 'active';

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

@@ -1,11 +1,18 @@
 {
   "name": "@stravica-ai/engineering-pa-core-extensions-atlassian",
-  "version": "0.1.1",
-  "description": "Atlassian (Jira/Confluence) core extension — optional, manifest-toggleable.",
+  "version": "0.2.0",
+  "description": "Atlassian (Jira, Confluence, confluence-fetch) CLIs and library surface. Promoted into core for the alpha solo scaffold.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
-    ".": "./index.mjs"
+    ".": "./index.mjs",
+    "./jira": "./src/jira/client.mjs",
+    "./confluence": "./src/confluence/client.mjs"
+  },
+  "bin": {
+    "jira": "bin/jira",
+    "confluence": "bin/confluence",
+    "confluence-fetch": "bin/confluence-fetch"
   },
   "private": true,
   "license": "MIT",
@@ -15,5 +22,5 @@
   "scripts": {
     "test": "node --test --test-isolation=none test/*.test.mjs"
   },
-  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper - see packages/cli/test/secrets. Counts must never lie."
 }

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

@@ -0,0 +1,137 @@
+// client.mjs - Shared fail-silent transport for notifying the local
+// workspace server that a CLI tool's backing data changed.
+//
+// Extracted so any Atlassian CLI (jira today; confluence or others later) can
+// fire a lightweight "hey, invalidate your cache" POST at a tool-specific
+// endpoint without re-implementing the fetch/timeout/disable-flag plumbing.
+// Callers bind their own endpoint, body shape, and disable env var (see
+// operator/extensions/tools/jira/src/invalidate.mjs for the reference
+// caller); this module only owns the wire mechanics.
+//
+// Contract (binding on every caller):
+//   - Fail-silent. Never throws - always resolves to { ok, error? }. A
+//     workspace-notify feature must never block or crash the CLI command
+//     whose actual job is mutating the upstream system (Jira, Confluence, ...).
+//   - Non-blocking by design. Bounded by timeoutMs (default 500ms) via
+//     AbortController; the caller gets an answer promptly either way.
+//   - Zero runtime deps. Node 20+ globalThis.fetch + AbortController only.
+//
+// Port resolution: opts.port wins; else the workspacePort from the merged
+// preferences (device-local preferences.local.json over the synced
+// preferences.json); else the platform default (4200) - same convention as
+// operator/extensions/tools/confluence-fetch/src/fetch.mjs.
+//
+// The overlay (preferences.local.json) is the operator's device-scoped
+// escape hatch: gitignored, so a per-device workspacePort never travels
+// through the synced base file. Precedence matches the platform's own
+// reader in engineering-pa-core src/desk/team-scope.mjs mergePreferences().
+
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+// Repo root: env override, else cwd. The tool is invoked from a workspace
+// root so cwd is the correct default; keeps preferences.local.json overlay
+// resolution working under a downstream install.
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+const PREFERENCES_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.json');
+const PREFERENCES_LOCAL_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.local.json');
+
+const DEFAULT_TIMEOUT_MS = 500;
+const PLATFORM_DEFAULT_PORT = 4200;
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    // Missing or malformed - that layer contributes nothing.
+    return null;
+  }
+}
+
+/**
+ * Resolve the local workspace port from the merged preferences.
+ * Overlay keys win; keys it omits fall through to the synced base; a device
+ * with no overlay behaves exactly as before this change.
+ *
+ * Paths are injectable for tests only - production callers pass nothing.
+ *
+ * @param {object} [paths]
+ * @param {string} [paths.base]   preferences.json path.
+ * @param {string} [paths.local]  preferences.local.json path.
+ * @returns {number}
+ */
+export function resolveWorkspacePort({ base = PREFERENCES_PATH, local = PREFERENCES_LOCAL_PATH } = {}) {
+  const prefs = { ...(readJsonObject(base) || {}), ...(readJsonObject(local) || {}) };
+  return typeof prefs.workspacePort === 'number' ? prefs.workspacePort : PLATFORM_DEFAULT_PORT;
+}
+
+function resolvePort(overridePort) {
+  if (typeof overridePort === 'number') return overridePort;
+  return resolveWorkspacePort();
+}
+
+/**
+ * Fire a fail-silent POST notify against the local workspace server.
+ * Always resolves; never throws.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint       Path to POST to, e.g. '/__api/jira/invalidate'.
+ * @param {string} [opts.disableEnv]   Env var name; value '0' short-circuits
+ *                                      (skips the network call entirely).
+ * @param {object} [opts.body]         JSON body to send. Defaults to {}.
+ * @param {number} [opts.port]         Override the resolved workspace port.
+ * @param {number} [opts.timeoutMs]    Override the abort timeout (default 500ms).
+ * @param {Function} [opts.fetchImpl]  Override fetch (test injection).
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function notifyInvalidate(opts = {}) {
+  const { endpoint, disableEnv, body = {}, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl } = opts;
+
+  if (disableEnv && process.env[disableEnv] === '0') {
+    return { ok: false, error: 'disabled' };
+  }
+
+  const fetchFn = typeof fetchImpl === 'function' ? fetchImpl : (fetchImpl || globalThis.fetch);
+  if (typeof fetchFn !== 'function') {
+    return { ok: false, error: 'fetch unavailable' };
+  }
+
+  const port = resolvePort(opts.port);
+  const url = `http://127.0.0.1:${port}${endpoint}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `http ${res.status}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Fire-and-forget wrapper. Returns immediately usable promise that never
+ * rejects, even if the caller doesn't await it - safe to call without a
+ * trailing .catch().
+ *
+ * @param {object} [opts]  Same shape as notifyInvalidate.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export function notifyInvalidateAsync(opts = {}) {
+  return notifyInvalidate(opts).catch((err) => ({
+    ok: false,
+    error: err && err.message ? err.message : String(err),
+  }));
+}

package/dist/engineering-pa-core-extensions-atlassian/src/common/pa-name.mjs

@@ -0,0 +1,58 @@
+// pa-name.mjs - Resolve the configured PA name for colleague-visible
+// artefacts (e.g. the marker prefix on Jira comments the CLIs post).
+//
+// Precedence:
+//   1. env PA_NAME - explicit per-shell override, wins outright.
+//   2. paName in the operator preferences (device-local
+//      preferences.local.json overlay over the synced preferences.json) -
+//      the scaffold writes this at pa-init time; it matches the
+//      `agents/<paName>/` directory shape.
+//   3. `'pa'` - a generic fallback so the marker is never blank.
+//
+// The reader mirrors invalidate-client.mjs on repo-root resolution and
+// preferences layering so operators get one story.
+
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const REPO_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+const PREFERENCES_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.json');
+const PREFERENCES_LOCAL_PATH = resolve(REPO_ROOT, 'operator', 'config', 'preferences.local.json');
+
+const DEFAULT_PA_NAME = 'pa';
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * Resolve the configured PA name.
+ *
+ * Paths are injectable for tests only - production callers pass nothing.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.envValue]  Override the PA_NAME env value (test injection).
+ * @param {string} [opts.base]      preferences.json path.
+ * @param {string} [opts.local]     preferences.local.json path.
+ * @returns {string}
+ */
+export function resolvePaName({
+  envValue = process.env.PA_NAME,
+  base = PREFERENCES_PATH,
+  local = PREFERENCES_LOCAL_PATH,
+} = {}) {
+  if (isNonEmptyString(envValue)) return envValue.trim();
+  const prefs = { ...(readJsonObject(base) || {}), ...(readJsonObject(local) || {}) };
+  if (isNonEmptyString(prefs.paName)) return prefs.paName.trim();
+  return DEFAULT_PA_NAME;
+}

package/dist/engineering-pa-core-extensions-atlassian/src/common/secrets.mjs

@@ -0,0 +1,158 @@
+// secrets.mjs - resolve Atlassian credentials for the jira and confluence
+// CLIs (and the shared client factories in src/jira, src/confluence).
+//
+// Both CLIs point at the same Atlassian site so the three required keys are
+// shared:
+//
+//   JIRA_DOMAIN     Atlassian subdomain, e.g. "yoursite" for yoursite.atlassian.net
+//   JIRA_EMAIL      Account email used with the API token
+//   JIRA_API_TOKEN  User-scoped API token from id.atlassian.com
+//
+// One optional key is also resolved on demand (never required):
+//
+//   JIRA_DEFAULT_PROJECT  Project key the `jira mine` verb narrows to when
+//                         the operator does not pass --project / --all. With
+//                         nothing configured, `mine` returns issues across
+//                         every project the account can see.
+//
+// Resolution order for each key:
+//   1. Explicit override via opts.secretsGet(key) (tests inject a function)
+//   2. Environment variable of the same name (JIRA_DOMAIN, ...)
+//   3. Platform `secrets` bin: `secrets get <ATLASSIAN_SECRETS_PREFIX?>KEY`
+//      Runs against the workspace-root vault the operator scaffold seeds.
+//      A prefix such as an org-slug like `acme/` (env var
+//      ATLASSIAN_SECRETS_PREFIX) picks a non-default scope via the platform
+//      full-scope reference form.
+//
+// The tool never prints or logs the values. All read paths run
+// `stdio: ['ignore', 'pipe', 'pipe']` and the caller's error strings never
+// interpolate the value.
+//
+// Zero npm dependencies. Uses node:child_process for the fallback bin call.
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Sentinel raised when a required credential cannot be resolved. Callers
+ * wrap this in their own JiraError / ConfluenceError with exit code 3.
+ */
+export class CredentialResolutionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CredentialResolutionError';
+  }
+}
+
+const KEYS = ['JIRA_DOMAIN', 'JIRA_EMAIL', 'JIRA_API_TOKEN'];
+
+/**
+ * Resolve a single Atlassian secret. Not for external use; the CLIs call
+ * loadAtlassianCredentials.
+ * @param {string} key
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {string}
+ */
+export function resolveSecret(key, opts = {}) {
+  if (typeof opts.secretsGet === 'function') {
+    const v = opts.secretsGet(key);
+    if (typeof v === 'string' && v.length > 0) return v.trim();
+    throw new CredentialResolutionError(`opts.secretsGet returned no value for ${key}`);
+  }
+
+  const env = opts.env ?? process.env;
+
+  const envValue = env[key];
+  if (typeof envValue === 'string' && envValue.length > 0) return envValue.trim();
+
+  const prefix = env.ATLASSIAN_SECRETS_PREFIX ?? '';
+  const scopedKey = `${prefix}${key}`;
+  const bin = opts.secretsBin ?? 'secrets';
+
+  try {
+    const out = execFileSync(bin, ['get', scopedKey], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    const trimmed = out.trim();
+    if (trimmed.length === 0) {
+      throw new CredentialResolutionError(
+        `platform \`secrets get ${scopedKey}\` returned empty output`,
+      );
+    }
+    return trimmed;
+  } catch (err) {
+    if (err instanceof CredentialResolutionError) throw err;
+    const stderrSnippet = err.stderr ? String(err.stderr).trim().split('\n').pop() : '';
+    const hint = stderrSnippet
+      ? ` (${stderrSnippet})`
+      : ' (bin missing? try `pnpm exec secrets get` from your operator repo)';
+    throw new CredentialResolutionError(
+      `could not read ${key} from env or \`secrets get ${scopedKey}\`${hint}`,
+    );
+  }
+}
+
+/**
+ * Resolve an OPTIONAL Atlassian setting. Same env -> secrets bin order as
+ * resolveSecret, but returns null instead of throwing when the key is
+ * absent so a caller can fall back to a "no default" branch cleanly. Used
+ * for JIRA_DEFAULT_PROJECT and any other future soft config the tools
+ * accept but never require.
+ *
+ * A missing env var and a bin call that exits non-zero, both return null;
+ * an empty string from the bin returns null too. Any other exec failure
+ * (bin missing, permission error) is swallowed so an operator without the
+ * `secrets` bin on PATH still gets the "no default" behaviour rather than
+ * a crash on an optional lookup. The primary credential path stays strict.
+ *
+ * @param {string} key
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {string | null}
+ */
+export function resolveOptionalSecret(key, opts = {}) {
+  if (typeof opts.secretsGet === 'function') {
+    try {
+      const v = opts.secretsGet(key);
+      if (typeof v === 'string' && v.length > 0) return v.trim();
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  const env = opts.env ?? process.env;
+
+  const envValue = env[key];
+  if (typeof envValue === 'string' && envValue.length > 0) return envValue.trim();
+
+  const prefix = env.ATLASSIAN_SECRETS_PREFIX ?? '';
+  const scopedKey = `${prefix}${key}`;
+  const bin = opts.secretsBin ?? 'secrets';
+
+  try {
+    const out = execFileSync(bin, ['get', scopedKey], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load all three Atlassian credentials. Test suites pass in
+ * `{ secretsGet: (key) => literal }` to skip both env vars and the bin.
+ *
+ * @param {{ secretsGet?: (key: string) => string, secretsBin?: string, env?: Record<string,string> }} opts
+ * @returns {{ domain: string, email: string, apiToken: string }}
+ */
+export function loadAtlassianCredentials(opts = {}) {
+  const domain = resolveSecret('JIRA_DOMAIN', opts);
+  const email = resolveSecret('JIRA_EMAIL', opts);
+  const apiToken = resolveSecret('JIRA_API_TOKEN', opts);
+  return { domain, email, apiToken };
+}