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

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

@@ -0,0 +1,405 @@
+// workflow-chains.mjs - Shared helpers for the Jira workflow chain config.
+//
+// The chain config encodes the forward transition chains for known project
+// workflows, keyed by project then issue type. It is resolved in a fixed
+// precedence order: an operator override at
+// operator/config/jira-workflow-chains.json first, then the default that
+// ships inside this tool at config/jira-workflow-chains.json. The shipped
+// default is what makes `advance` work on a fresh compose with no setup
+// step; the override exists so an estate can carry its own workflows
+// without editing the tool. Each chain is a list of directed edges:
+//
+//   { "from": "<status>", "transition": "<verb>", "to": "<status>",
+//     "gate": { "applyVia": "update", "fields": ["ticketType", ...] },
+//     "shortcut": true, "skips": ["<status>", ...] }
+//
+// The `gate` is optional. When present it declares fields that must be
+// populated BEFORE the transition fires (the workflow's transition screen
+// rejects field flags, so they go via `jira update` first). Gate field
+// kinds are symbolic: "ticketType", "affectedServices", "originalEstimate".
+//
+// `shortcut` is also optional and encodes the close-vs-next routing
+// contract. A shortcut edge is a real forward transition that skips
+// intermediate states. It exists in Jira and it is the wanted route when
+// the operator says "close it", but it must never be the answer to "move
+// it on one step". So shortcut edges are excluded from routing by default
+// and only opted into (`allowShortcuts`) by the close mode - and never by
+// computeNextEdge, which is what backs the single-hop next mode.
+//
+// An issue type may also declare a consent policy:
+//
+//   "consent": { "required": true, "reason": "<why>" }
+//
+// which makes `advance` refuse the type unless the operator passes the
+// explicit consent flag. Encoded for Epics: an Epic's status is a scope
+// judgement, not a mechanical consequence of its children closing.
+//
+// This module is pure data access + graph computation - no API calls.
+// Zero external dependencies; Node.js built-ins only.
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile as fsReadFile } from 'node:fs/promises';
+
+// ── Path resolution ──────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Project root: env override, else cwd. The tool is invoked from a
+// workspace root so cwd is the correct default.
+const DEFAULT_PROJECT_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+
+// Operator override, relative to the project root. This path is a
+// composition mount (fed from the operator entity), so the tool must not
+// depend on anything being there.
+export const CHAINS_REL_PATH = 'operator/config/jira-workflow-chains.json';
+
+// Tool-shipped default (empty chains list, per-site config). From
+// src/jira/ up two to the package root, then config/.
+export const SHIPPED_CHAINS_PATH = resolve(
+  __dirname, '..', '..', 'config', 'jira-workflow-chains.default.json'
+);
+
+// Fallback when the config carries no fieldIds block. Matches the AI
+// project's "Ticket Type" select customfield.
+export const DEFAULT_TICKET_TYPE_FIELD_ID = 'customfield_11535';
+
+// ── Loading ──────────────────────────────────────────────────────────
+
+/**
+ * The paths loadChains consults, in precedence order. Exported so error
+ * messages can name the real search order rather than one hard-coded path.
+ *
+ * @param {string} [projectRoot]  Project root directory (default: auto-detected)
+ * @returns {string[]}            Absolute paths, highest precedence first
+ */
+export function chainsSearchPaths(projectRoot) {
+  const root = projectRoot || DEFAULT_PROJECT_ROOT;
+  return [resolve(root, CHAINS_REL_PATH), SHIPPED_CHAINS_PATH];
+}
+
+/**
+ * Load the workflow chain config from disk. Tries the operator override
+ * first and falls back to the tool-shipped default when it is absent. An
+ * override that exists but does not parse is NOT skipped - a broken
+ * override is an operator mistake and must be loud, not silently masked
+ * by the default.
+ *
+ * @param {string} [projectRoot]  Project root directory (default: auto-detected)
+ * @param {object} [deps]         Dependency overrides for testing
+ * @param {Function} [deps.readFile]  readFile override
+ * @returns {Promise<object>}     Parsed chains object
+ * @throws {Error}                If no candidate is readable, or the one
+ *                                that was read is invalid JSON
+ */
+export async function loadChains(projectRoot, deps = {}) {
+  const readFile = deps.readFile || ((p) => fsReadFile(p, 'utf-8'));
+  let lastErr = null;
+  for (const chainsPath of chainsSearchPaths(projectRoot)) {
+    let raw;
+    try {
+      raw = await readFile(chainsPath);
+    } catch (err) {
+      lastErr = err;
+      continue;
+    }
+    return JSON.parse(raw);
+  }
+  throw lastErr;
+}
+
+/**
+ * Get the Ticket Type field id from the config (with fallback).
+ *
+ * @param {object} [chains]  The loaded chain config
+ * @returns {string}         Field id (e.g. "customfield_11535")
+ */
+export function getTicketTypeFieldId(chains) {
+  return chains?.fieldIds?.ticketType || DEFAULT_TICKET_TYPE_FIELD_ID;
+}
+
+/**
+ * Get the whole chain config node for a project + issue type (edges plus
+ * the type-level metadata: consent policy, doneStatus, notes). Both
+ * lookups are case-insensitive so "bug" finds "Bug".
+ *
+ * @param {object} chains     The loaded chain config
+ * @param {string} projectKey Jira project key (e.g. "PROJ")
+ * @param {string} issueType  Issue type name (e.g. "Bug", "Task", "Epic")
+ * @returns {object|null}     The issue-type node, or null when unconfigured
+ */
+export function getChainConfig(chains, projectKey, issueType) {
+  const projects = chains?.projects;
+  if (!projects) return null;
+
+  const projKey = findKeyInsensitive(projects, projectKey);
+  if (!projKey) return null;
+
+  const issueTypes = projects[projKey]?.issueTypes;
+  if (!issueTypes) return null;
+
+  const typeKey = findKeyInsensitive(issueTypes, issueType);
+  if (!typeKey) return null;
+
+  return issueTypes[typeKey] || null;
+}
+
+/**
+ * Get the chain edges for a project + issue type.
+ *
+ * @param {object} chains     The loaded chain config
+ * @param {string} projectKey Jira project key (e.g. "PROJ")
+ * @param {string} issueType  Issue type name (e.g. "Bug", "Task", "Epic")
+ * @returns {object[]|null}   Edge list, or null when unconfigured
+ */
+export function getChainEdges(chains, projectKey, issueType) {
+  const edges = getChainConfig(chains, projectKey, issueType)?.edges;
+  return Array.isArray(edges) && edges.length > 0 ? edges : null;
+}
+
+/**
+ * Read the consent policy off an issue type's chain config. Issue types
+ * whose status is an operator judgement rather than a mechanical
+ * consequence of the work declare `consent.required`, and `advance`
+ * refuses them without the explicit consent flag.
+ *
+ * @param {object|null} chainConfig  From getChainConfig
+ * @returns {{required: boolean, reason: string|null}}
+ */
+export function getConsentPolicy(chainConfig) {
+  const consent = chainConfig?.consent;
+  return {
+    required: Boolean(consent?.required),
+    reason: consent?.reason || null,
+  };
+}
+
+/**
+ * List configured issue type names for a project (for error messages).
+ *
+ * @param {object} chains     The loaded chain config
+ * @param {string} projectKey Jira project key
+ * @returns {string[]}
+ */
+export function listConfiguredIssueTypes(chains, projectKey) {
+  const projects = chains?.projects;
+  if (!projects) return [];
+  const projKey = findKeyInsensitive(projects, projectKey);
+  if (!projKey) return [];
+  return Object.keys(projects[projKey]?.issueTypes || {});
+}
+
+// ── Graph computation ────────────────────────────────────────────────
+
+/**
+ * Is this edge a shortcut (a real forward transition that skips
+ * intermediate states)?
+ *
+ * @param {object} edge
+ * @returns {boolean}
+ */
+export function isShortcutEdge(edge) {
+  return Boolean(edge?.shortcut);
+}
+
+/**
+ * All distinct statuses appearing in a chain (from + to), in edge order.
+ *
+ * @param {object[]} edges
+ * @returns {string[]}
+ */
+export function chainStatuses(edges) {
+  const seen = new Set();
+  const out = [];
+  for (const e of edges) {
+    for (const s of [e.from, e.to]) {
+      const k = String(s).toLowerCase();
+      if (!seen.has(k)) {
+        seen.add(k);
+        out.push(s);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve a target-status input against the chain's known statuses.
+ * Match order: case-insensitive exact, then unique case-insensitive
+ * substring. Returns the canonical status name, or null when nothing
+ * matches. Throws on ambiguous substring matches.
+ *
+ * @param {object[]} edges  Chain edges
+ * @param {string} input    Operator-supplied target status
+ * @returns {string|null}
+ * @throws {Error}          On ambiguity (message lists candidates)
+ */
+export function resolveTargetStatus(edges, input) {
+  const statuses = chainStatuses(edges);
+  const needle = String(input).toLowerCase();
+
+  const exact = statuses.find((s) => s.toLowerCase() === needle);
+  if (exact) return exact;
+
+  const partial = statuses.filter((s) => s.toLowerCase().includes(needle));
+  if (partial.length === 1) return partial[0];
+  if (partial.length > 1) {
+    const err = new Error(
+      `Ambiguous target status "${input}" - matches: ${partial.join(', ')}`
+    );
+    err.ambiguous = partial;
+    throw err;
+  }
+  return null;
+}
+
+/**
+ * Compute the shortest forward path from one status to another via BFS
+ * over the chain edges. Status comparison is case-insensitive.
+ *
+ * Shortcut edges are EXCLUDED by default. Left in, BFS would prefer them
+ * for every target - including intermediate ones - and an operator asking
+ * for "Merge" or "Ready for PROD" would silently skip states they asked
+ * to pass through. Only the close mode opts in.
+ *
+ * @param {object[]} edges   Chain edges
+ * @param {string} from      Current status
+ * @param {string} target    Target status (canonical, from resolveTargetStatus)
+ * @param {object} [options]
+ * @param {boolean} [options.allowShortcuts=false]  Route through shortcut edges
+ * @returns {object[]|null}  Ordered list of edges to walk, or null if
+ *                           unreachable. Empty array when from === target.
+ */
+export function computePath(edges, from, target, options = {}) {
+  const { allowShortcuts = false } = options;
+  const usable = allowShortcuts ? edges : edges.filter((e) => !isShortcutEdge(e));
+
+  const norm = (s) => String(s).toLowerCase();
+  const start = norm(from);
+  const goal = norm(target);
+  if (start === goal) return [];
+
+  // BFS - queue of { status, path }.
+  const visited = new Set([start]);
+  const queue = [{ status: start, path: [] }];
+
+  while (queue.length > 0) {
+    const { status, path } = queue.shift();
+    for (const edge of usable) {
+      if (norm(edge.from) !== status) continue;
+      const next = norm(edge.to);
+      if (visited.has(next)) continue;
+      const nextPath = [...path, edge];
+      if (next === goal) return nextPath;
+      visited.add(next);
+      queue.push({ status: next, path: nextPath });
+    }
+  }
+  return null;
+}
+
+/**
+ * The single forward edge leaving a status - what backs the `next` mode
+ * ("do the next logical workflow status step").
+ *
+ * Shortcut edges are filtered out of the candidate set entirely, not
+ * merely deprioritised, so `next` provably cannot take one. This is the
+ * Task memory's "do NOT jump to Work Complete until merged" rule
+ * expressed in code: the shortcut still exists for `close`, and `next`
+ * can never reach it.
+ *
+ * @param {object[]} edges  Chain edges
+ * @param {string} from     Current status
+ * @returns {object|null}   The single forward edge, or null when the
+ *                          status has no non-shortcut forward edge
+ * @throws {Error}          When more than one forward edge leaves the
+ *                          status (message lists them; err.candidates
+ *                          carries the edges)
+ */
+export function computeNextEdge(edges, from) {
+  const norm = (s) => String(s).toLowerCase();
+  const start = norm(from);
+  const candidates = edges.filter(
+    (e) => norm(e.from) === start && !isShortcutEdge(e)
+  );
+
+  if (candidates.length === 0) return null;
+  if (candidates.length === 1) return candidates[0];
+
+  const listed = candidates
+    .map((e) => `"${e.transition}" → ${e.to}`)
+    .join(', ');
+  const err = new Error(
+    `"${from}" has ${candidates.length} forward steps - ${listed}. ` +
+    'Name the target status explicitly rather than using --next.'
+  );
+  err.candidates = candidates;
+  throw err;
+}
+
+/**
+ * The chain's terminal "done" status - what `close` aims at.
+ *
+ * Resolution order: an explicit `doneStatus` on the issue-type config, a
+ * status literally named "Done", then the unique sink (a status with no
+ * forward edges). Anything less certain returns null so the caller can
+ * fail loudly rather than close a ticket into a guessed state.
+ *
+ * @param {object[]} edges          Chain edges
+ * @param {object} [chainConfig]    Issue-type node from getChainConfig
+ * @returns {string|null}           Canonical status name, or null
+ */
+export function resolveDoneStatus(edges, chainConfig) {
+  const statuses = chainStatuses(edges);
+  const norm = (s) => String(s).toLowerCase();
+
+  const declared = chainConfig?.doneStatus;
+  if (declared) {
+    return statuses.find((s) => norm(s) === norm(declared)) || null;
+  }
+
+  const named = statuses.find((s) => norm(s) === 'done');
+  if (named) return named;
+
+  const sinks = statuses.filter(
+    (s) => !edges.some((e) => norm(e.from) === norm(s))
+  );
+  return sinks.length === 1 ? sinks[0] : null;
+}
+
+/**
+ * Statuses reachable from a given status (for unreachable-target errors).
+ * Considers shortcut edges too - this answers "what can this ticket get
+ * to at all", which is the honest thing to print when a target is
+ * unreachable by any route.
+ *
+ * @param {object[]} edges
+ * @param {string} from
+ * @returns {string[]}  Canonical status names reachable in one or more hops
+ */
+export function reachableStatuses(edges, from) {
+  const norm = (s) => String(s).toLowerCase();
+  const visited = new Set([norm(from)]);
+  const out = [];
+  const queue = [norm(from)];
+  while (queue.length > 0) {
+    const status = queue.shift();
+    for (const edge of edges) {
+      if (norm(edge.from) !== status) continue;
+      const next = norm(edge.to);
+      if (visited.has(next)) continue;
+      visited.add(next);
+      out.push(edge.to);
+      queue.push(next);
+    }
+  }
+  return out;
+}
+
+// ── Internal ─────────────────────────────────────────────────────────
+
+function findKeyInsensitive(obj, key) {
+  const needle = String(key).toLowerCase();
+  return Object.keys(obj).find((k) => k.toLowerCase() === needle) || null;
+}

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

@@ -0,0 +1,107 @@
+// workflow-map.mjs - Shared helpers for reading the Jira workflow status map.
+//
+// The map is written by `jira sync-statuses` to operator/config/jira-status-mappings.json.
+// This module provides read-only access to the computed workflow metadata:
+// terminal statuses, cancelled equivalents, and JQL exclusion clauses.
+//
+// Zero external dependencies - uses only Node.js built-ins.
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile as fsReadFile } from 'node:fs/promises';
+
+// ── Path resolution ──────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Project root: env override, else cwd. The tool is invoked from a
+// workspace root so cwd is the correct default.
+const DEFAULT_PROJECT_ROOT =
+  process.env.PA_REPO_ROOT || process.env.DAVE_ROOT || process.cwd();
+
+const MAPPINGS_REL_PATH = 'operator/config/jira-status-mappings.json';
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Load the workflow status map from disk.
+ *
+ * @param {string} [projectRoot]  Project root directory (default: auto-detected)
+ * @param {object} [deps]         Dependency overrides for testing
+ * @param {Function} [deps.readFile]  readFile override
+ * @returns {Promise<object>}     Parsed mappings object
+ * @throws {Error}                If the file does not exist or is invalid JSON
+ */
+export async function loadMap(projectRoot, deps = {}) {
+  const root = projectRoot || DEFAULT_PROJECT_ROOT;
+  const readFile = deps.readFile || ((p) => fsReadFile(p, 'utf-8'));
+  const mappingsPath = resolve(root, MAPPINGS_REL_PATH);
+  const raw = await readFile(mappingsPath);
+  return JSON.parse(raw);
+}
+
+/**
+ * Get terminal statuses for a specific project.
+ *
+ * @param {object} map         The loaded workflow map
+ * @param {string} projectKey  Jira project key (e.g. "PROJ")
+ * @returns {string[]}         Array of terminal status names, or empty array
+ */
+export function getTerminalStatuses(map, projectKey) {
+  const project = map?.projects?.[projectKey];
+  if (!project) return [];
+  return project.terminalStatuses || [];
+}
+
+/**
+ * Get the cancelled-equivalent status for a specific project.
+ *
+ * @param {object} map         The loaded workflow map
+ * @param {string} projectKey  Jira project key (e.g. "PROJ")
+ * @returns {string|null}      Cancelled-equivalent status name, or null
+ */
+export function getCancelledEquivalent(map, projectKey) {
+  const project = map?.projects?.[projectKey];
+  if (!project) return null;
+  return project.cancelledEquivalent || null;
+}
+
+/**
+ * Build a JQL exclusion clause from all unique terminal statuses across all projects.
+ *
+ * Returns a fragment like: status NOT IN ("Done", "Cancelled", "Closed")
+ *
+ * @param {object} map  The loaded workflow map
+ * @returns {string}    JQL fragment, or empty string if no terminal statuses exist
+ */
+export function buildExclusionClause(map) {
+  const projects = map?.projects;
+  if (!projects) return '';
+
+  const allTerminal = new Set();
+  for (const project of Object.values(projects)) {
+    const terminal = project.terminalStatuses || [];
+    for (const status of terminal) {
+      allTerminal.add(status);
+    }
+  }
+
+  if (allTerminal.size === 0) return '';
+
+  const quoted = [...allTerminal].sort().map((s) => `"${s}"`);
+  return `status NOT IN (${quoted.join(', ')})`;
+}
+
+/**
+ * Check if the workflow map is stale (older than maxAgeMs).
+ *
+ * @param {object} map        The loaded workflow map
+ * @param {number} maxAgeMs   Maximum age in milliseconds
+ * @returns {boolean}         True if the map is stale or has no lastSynced timestamp
+ */
+export function isStale(map, maxAgeMs) {
+  if (!map?.lastSynced) return true;
+  const syncedAt = new Date(map.lastSynced).getTime();
+  if (isNaN(syncedAt)) return true;
+  return Date.now() - syncedAt > maxAgeMs;
+}

package/dist/engineering-pa-scaffold/README.md

@@ -43,6 +43,8 @@ pa-init --mode=solo --non-interactive --name=... --operator=... --target=...
                                  # CI mode; refuses to prompt
 pa-init --mode=lead              # exits 2 ("not implemented in Phase 1")
 pa-init --mode=member --invite=T # exits 2 ("not implemented in Phase 1")
+pa-init workspace-extension <name> [--label=LABEL] [--section=SECTION] [--with-api] [--target=DIR]
+                                 # scaffold one workspace-extension page inside an existing operator repo
 ```
 
 ### Flags
@@ -52,12 +54,40 @@ pa-init --mode=member --invite=T # exits 2 ("not implemented in Phase 1")
 | `--mode=MODE` | `solo` \| `lead` \| `member` (only `solo` ships in Phase 1) |
 | `--name=PA_NAME` | PA identity. Kebab-case, lowercase, 2-40 chars, starts with a letter. |
 | `--operator=NAME` | Operator (human) name. Free-form, 1-80 chars. |
-| `--target=DIR` | Target directory. Must be empty or not exist. |
+| `--target=DIR` | Target directory. `--mode=solo`: must be empty or not exist. Sub-verbs: defaults to cwd. |
 | `--purpose=TEXT` | Optional one-line PA purpose statement. Has a sane default. |
 | `--non-interactive` | Refuse to prompt. Requires all values via flags. CI-friendly. |
 | `--skip-install` | Skip the post-scaffold `pnpm install` + `pa status` check (test-friendly). |
+| `--label=LABEL` | (workspace-extension) Sidebar label. Defaults to Title Case of the name. |
+| `--section=SECTION` | (workspace-extension) Nav section header. Defaults to "Extensions". |
+| `--with-api` | (workspace-extension) Also write an `<name>-api.mjs` `register(addRoute)` stub. |
 | `-h`, `--help` | Show usage, exit 0. |
 
+### Sub-verb: `workspace-extension`
+
+Scaffolds one workspace-extension page inside an existing operator repo. The
+PA-facing prompting guide at
+`operator/knowledge/platform-tooling/workspace-extensions.md` covers the
+"when to propose one" question; this verb covers the "yes, do it" cost.
+
+What it writes:
+
+- `operator/extensions/workspace/<name>.html`: a minimal HTML skeleton with
+  the extension name in a marker comment.
+- `operator/extensions/workspace/nav.json`: appends a
+  `{ id, label, href, section }` entry (creates the file if absent).
+- `operator/extensions/workspace/<name>-api.mjs`: optional, on `--with-api`.
+  Exports `register(addRoute)` and wires one placeholder GET route so the
+  extension responds before the operator writes any handler code.
+
+Idempotency:
+
+- A second run with the same `<name>` skips existing files instead of
+  overwriting them.
+- Same-`id` collisions in an existing `nav.json` are left as-is and reported;
+  malformed `nav.json` fails cleanly with exit 2 rather than corrupting the
+  file.
+
 ## Exit codes (tooling standard §6)
 
 | Code | Meaning |
@@ -126,6 +156,7 @@ packages/scaffold/
     runner.mjs                 # CHOKEPOINT: writes files, spawns pnpm/pa/git
     commands/
       init.mjs                 # --mode=solo orchestration
+      init-workspace-extension.mjs  # workspace-extension <name> orchestration
   templates/
     CLAUDE.md.template         # PA identity template, {PA_NAME}/{OPERATOR_NAME}/{PURPOSE}/{COMMUNICATION_STYLE} tokens
     operator-README.md.template# operator-repo README template