@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/desk/commands.mjs

@@ -0,0 +1,398 @@
+// desk — command implementations
+// Each command is a plain async function returning an exit code.
+// Output is written to stdout directly; formatting lives in format.mjs.
+
+import { listProjects, getProject, listWork, getWork, sortByStateThenPriority, STATE_ORDER, getRepoRoot } from './repo.mjs';
+import { colour, bold, dim, statusBadge, categoryBadge, priorityLabel, truncate, padEnd, header, kv } from './format.mjs';
+import { filterProjectsByTeam, readTeamScopeConfig, parseTeamScopeFlags } from './team-scope.mjs';
+
+// Read PA name + team-scope config from operator config. Falls back to
+// paName 'pa', scoping disabled (backward compat — see team-scope.mjs).
+async function getDeskConfig() {
+  const repoRoot = await getRepoRoot();
+  return readTeamScopeConfig(repoRoot);
+}
+
+// Kept as a thin wrapper — callers elsewhere in this file only need the name.
+async function getPaName() {
+  return (await getDeskConfig()).paName;
+}
+
+// Apply the team-scoping filter to a project list, then (for human output
+// only) print a one-line notice when projects were hidden by the default
+// scoped view — the fail-open design still means the operator should know
+// scoping is active, not just silently see a shorter list.
+function scopeProjects(projects, config, teamFlags, { json = false } = {}) {
+  const scoped = filterProjectsByTeam(projects, {
+    selfIdentities: config.teamIdentities,
+    scopeEnabled: config.scopeEnabled,
+    allTeams: teamFlags.allTeams,
+    team: teamFlags.team,
+  });
+  const hiddenCount = projects.length - scoped.length;
+  if (!json && hiddenCount > 0 && !teamFlags.team) {
+    console.log(dim(`  (${hiddenCount} other-team project${hiddenCount === 1 ? '' : 's'} hidden — use --all-teams to show)`));
+  }
+  return scoped;
+}
+
+function matchesFilter(item, filters) {
+  if (filters.status && item.status !== filters.status) return false;
+  if (filters.project && item.projectId !== filters.project) return false;
+  if (filters.category && item.category !== filters.category) return false;
+  if (filters.owner && item.owner !== filters.owner) return false;
+  if (filters.assignee) {
+    if (filters.assignee === 'unassigned') {
+      if (item.assignee) return false;
+    } else if (item.assignee !== filters.assignee) {
+      return false;
+    }
+  }
+  if (filters.mine && item.assignee !== filters.paName) return false;
+  if (filters.theirs && item.assignee !== 'operator') return false;
+  return true;
+}
+
+function parseFilters(args) {
+  const f = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--status') f.status = args[++i];
+    else if (a === '--project') f.project = args[++i];
+    else if (a === '--category') f.category = args[++i];
+    else if (a === '--owner') f.owner = args[++i];
+    else if (a === '--assignee') f.assignee = args[++i];
+    else if (a === '--mine') f.mine = true;
+    else if (a === '--theirs') f.theirs = true;
+    else if (a === '--all') f.all = true;
+    else if (a === '--json') f.json = true;
+    else if (a === '--all-teams') f.allTeams = true;
+    else if (a === '--team') f.team = args[++i];
+    else if (!f._rest) f._rest = [a];
+    else f._rest.push(a);
+  }
+  return f;
+}
+
+// --- projects ---
+
+export async function projectsList(args) {
+  const filters = parseFilters(args);
+  const config = await getDeskConfig();
+  const allProjects = await listProjects();
+  const scopedProjects = scopeProjects(allProjects, config, filters, { json: filters.json });
+  const filtered = filters.all
+    ? scopedProjects
+    : scopedProjects.filter((p) => !['done', 'archived'].includes(p.status));
+
+  if (filters.json) {
+    console.log(JSON.stringify(filtered, null, 2));
+    return 0;
+  }
+
+  if (!filtered.length) {
+    console.log(dim(filters.all ? 'No projects.' : 'No active projects. Use --all to include done/archived.'));
+    return 0;
+  }
+
+  // Group by status.
+  const groups = new Map();
+  for (const p of filtered) {
+    const s = p.status || 'draft';
+    if (!groups.has(s)) groups.set(s, []);
+    groups.get(s).push(p);
+  }
+
+  for (const s of STATE_ORDER) {
+    const items = groups.get(s);
+    if (!items || !items.length) continue;
+    items.sort((a, b) => {
+      const pa = a.priority == null ? 99 : a.priority;
+      const pb = b.priority == null ? 99 : b.priority;
+      if (pa !== pb) return pa - pb;
+      return (a.number || 999) - (b.number || 999);
+    });
+    console.log(header(`${s} (${items.length})`));
+    for (const p of items) {
+      const num = p.number != null ? dim(`#${p.number}`) : dim('  ');
+      const prio = priorityLabel(p.priority);
+      const id = colour('cyan', p.id);
+      const name = p.name || '';
+      const cat = p.category ? dim(`[${p.category}]`) : '';
+      console.log(`  ${padEnd(num, 4)} ${prio}  ${padEnd(id, 24)} ${name} ${cat}`);
+    }
+  }
+  console.log('');
+  return 0;
+}
+
+export async function projectShow(args) {
+  const id = args[0];
+  if (!id) {
+    console.error('usage: desk projects show <id>');
+    return 1;
+  }
+  const p = await getProject(id);
+  if (!p) {
+    console.error(`project not found: ${id}`);
+    return 1;
+  }
+  console.log(header(p.name || p.id));
+  console.log(kv('id', colour('cyan', p.id)));
+  if (p.number != null) console.log(kv('number', `#${p.number}`));
+  console.log(kv('status', statusBadge(p.status || 'draft')));
+  console.log(kv('priority', priorityLabel(p.priority)));
+  if (p.category) console.log(kv('category', p.category));
+  if (p.lead) console.log(kv('lead', p.lead));
+  if (p.owner) console.log(kv('owner', p.owner));
+  if (p.executor) console.log(kv('executor', p.executor));
+  if (p.created) console.log(kv('created', p.created));
+  if (p.shipped) console.log(kv('shipped', p.shipped));
+  if (p.path) console.log(kv('path', dim(p.path)));
+  if (p.summary) {
+    console.log('');
+    console.log('  ' + p.summary);
+  }
+  if (p.docs && p.docs.length) {
+    console.log('');
+    console.log(bold('  docs'));
+    for (const d of p.docs) {
+      console.log(`    ${dim('·')} ${d.label} ${dim(d.path)}`);
+    }
+  }
+  // Related work items.
+  const work = (await listWork()).filter((w) => w.projectId === p.id);
+  if (work.length) {
+    console.log('');
+    console.log(bold(`  work items (${work.length})`));
+    for (const w of sortByStateThenPriority(work)) {
+      console.log(`    ${statusBadge(w.status)} ${priorityLabel(w.priority)} ${colour('cyan', w.id)} ${truncate(w.title, 70)}`);
+    }
+  }
+  console.log('');
+  return 0;
+}
+
+// --- work ---
+
+export async function workList(args) {
+  const filters = parseFilters(args);
+  const paName = await getPaName();
+  filters.paName = paName;
+
+  const items = await listWork();
+  let filtered = items.filter((w) => matchesFilter(w, filters));
+  if (!filters.all && !filters.status) {
+    filtered = filtered.filter((w) => !['done', 'archived'].includes(w.status));
+  }
+
+  if (filters.json) {
+    console.log(JSON.stringify(filtered, null, 2));
+    return 0;
+  }
+
+  if (!filtered.length) {
+    console.log(dim('No work items match.'));
+    return 0;
+  }
+
+  const sorted = sortByStateThenPriority(filtered);
+  const groups = new Map();
+  for (const w of sorted) {
+    const s = w.status || 'draft';
+    if (!groups.has(s)) groups.set(s, []);
+    groups.get(s).push(w);
+  }
+
+  const DISPLAY_ORDER = ['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived'];
+  for (const s of DISPLAY_ORDER) {
+    const group = groups.get(s);
+    if (!group || !group.length) continue;
+    console.log(header(`${s} (${group.length})`));
+    for (const w of group) {
+      const prio = priorityLabel(w.priority);
+      const id = colour('cyan', w.id);
+      const cat = w.category ? categoryBadge(w.category) : '';
+      const proj = w.projectId ? dim(`[${w.projectId}]`) : dim('[—]');
+      const assignee = assigneeBadge(w.assignee, paName);
+      const title = truncate(w.title || '', 50);
+      console.log(`  ${prio}  ${padEnd(id, 22)} ${padEnd(assignee, 12)} ${padEnd(proj, 22)} ${padEnd(cat, 10)} ${title}`);
+    }
+  }
+  console.log('');
+  return 0;
+}
+
+function assigneeBadge(assignee, paName = 'pa') {
+  if (!assignee) return dim('—');
+  if (assignee === 'operator') return colour('orange', 'on you');
+  if (assignee === paName) return colour('cyan', 'on me');
+  return dim(`@${assignee}`);
+}
+
+export async function workShow(args) {
+  const id = args[0];
+  if (!id) {
+    console.error('usage: desk work show <id>');
+    return 1;
+  }
+  const w = await getWork(id);
+  if (!w) {
+    console.error(`work item not found: ${id}`);
+    return 1;
+  }
+  const paName = await getPaName();
+  console.log(header(w.title || w.id));
+  console.log(kv('id', colour('cyan', w.id)));
+  console.log(kv('status', statusBadge(w.status || 'draft')));
+  console.log(kv('priority', priorityLabel(w.priority)));
+  if (w.category) console.log(kv('category', categoryBadge(w.category)));
+  if (w.projectId) console.log(kv('project', w.projectId));
+  if (w.owner) console.log(kv('owner', w.owner));
+  console.log(kv('assignee', assigneeBadge(w.assignee, paName)));
+  if (w.created) console.log(kv('created', w.created));
+  if (w.updated) console.log(kv('updated', w.updated));
+  if (w.blocked) console.log(kv('blocked', colour('red', w.blocked)));
+  if (w.summary) {
+    console.log('');
+    console.log('  ' + w.summary);
+  }
+  if (w.links && w.links.length) {
+    console.log('');
+    console.log(bold('  links'));
+    for (const l of w.links) {
+      console.log(`    ${dim('·')} ${l.label} ${dim(l.path)}`);
+    }
+  }
+  console.log('');
+  return 0;
+}
+
+// --- overview ---
+
+export async function overview(args = []) {
+  const teamFlags = parseTeamScopeFlags(args);
+  const config = await getDeskConfig();
+  const paName = config.paName;
+  const allProjects = await listProjects();
+  const projects = scopeProjects(allProjects, config, teamFlags);
+  const work = await listWork();
+
+  const activeProjects = projects.filter((p) => !['done', 'archived'].includes(p.status));
+  const activeWork = work.filter((w) => !['done', 'archived'].includes(w.status));
+
+  const onMeWork = activeWork.filter((w) => w.assignee === paName);
+  const onYouWork = activeWork.filter((w) => w.assignee === 'operator');
+  const onMeProjects = activeProjects.filter((p) => p.assignee === paName);
+  const onYouProjects = activeProjects.filter((p) => p.assignee === 'operator');
+
+  const countByStatus = (arr) => {
+    const m = new Map();
+    for (const x of arr) {
+      const s = x.status || 'draft';
+      m.set(s, (m.get(s) || 0) + 1);
+    }
+    return m;
+  };
+  const projBy = countByStatus(activeProjects);
+  const workBy = countByStatus(activeWork);
+
+  console.log(header('Overview'));
+  console.log(`  ${bold('Projects')}: ${activeProjects.length} active, ${projects.length - activeProjects.length} done/archived`);
+  for (const s of STATE_ORDER) {
+    const n = projBy.get(s);
+    if (n) console.log(`    ${statusBadge(s)} ${n}`);
+  }
+  console.log(`  ${bold('Work items')}: ${activeWork.length} active, ${work.length - activeWork.length} done/archived`);
+  for (const s of STATE_ORDER) {
+    const n = workBy.get(s);
+    if (n) console.log(`    ${statusBadge(s)} ${n}`);
+  }
+
+  const onMe = onMeWork.length + onMeProjects.length;
+  const onYou = onYouWork.length + onYouProjects.length;
+  if (onMe || onYou) {
+    console.log(`  ${bold('Assignment')}: ${colour('cyan', 'on me')} ${onMe} · ${colour('orange', 'on you')} ${onYou}`);
+  }
+
+  if (onYou) {
+    console.log(header('On the Operator'));
+    for (const p of onYouProjects) {
+      console.log(`  ${colour('orange', '⏵')} ${bold(p.name || p.id)} ${dim('[project]')}`);
+      if (p.summary) console.log(`    ${dim(truncate(p.summary, 100))}`);
+    }
+    for (const w of onYouWork) {
+      console.log(`  ${colour('orange', '⏵')} ${w.title} ${dim(`[${w.id}]`)}`);
+    }
+  }
+
+  const inProgressProjects = activeProjects.filter((p) => p.status === 'in-progress');
+  const inProgressWork = activeWork.filter((w) => w.status === 'in-progress');
+  if (inProgressProjects.length || inProgressWork.length) {
+    console.log(header('In Progress'));
+    for (const p of inProgressProjects) {
+      console.log(`  ${colour('cyan', '◆')} ${bold(p.name || p.id)} ${dim('[project]')}`);
+      if (p.summary) console.log(`    ${dim(truncate(p.summary, 100))}`);
+    }
+    for (const w of inProgressWork) {
+      console.log(`  ${colour('cyan', '○')} ${w.title} ${dim(`[${w.id}]`)}`);
+    }
+  }
+
+  const blocked = [...activeProjects, ...activeWork].filter((x) => x.status === 'blocked');
+  if (blocked.length) {
+    console.log(header('Blocked'));
+    for (const x of blocked) {
+      console.log(`  ${colour('red', '⚠')} ${x.title || x.name || x.id}`);
+      if (x.blocked) console.log(`    ${dim('└─')} ${x.blocked}`);
+    }
+  }
+
+  const planned = sortByStateThenPriority(
+    [...activeProjects, ...activeWork].filter((x) => x.status === 'planned')
+  ).slice(0, 10);
+  if (planned.length) {
+    console.log(header('Next up (planned)'));
+    for (const x of planned) {
+      const type = 'number' in x ? 'project' : 'work';
+      console.log(`  ${priorityLabel(x.priority)} ${x.title || x.name} ${dim(`[${type}]`)}`);
+    }
+  }
+
+  console.log('');
+  return 0;
+}
+
+// --- today ---
+
+export async function today(args = []) {
+  const todayStr = new Date().toISOString().slice(0, 10);
+  const teamFlags = parseTeamScopeFlags(args);
+  const config = await getDeskConfig();
+  const allProjects = await listProjects();
+  const projects = scopeProjects(allProjects, config, teamFlags);
+  const work = await listWork();
+
+  const touched = [
+    ...projects.filter((p) => p.created === todayStr || p.shipped === todayStr),
+    ...work.filter((w) => w.created === todayStr || w.updated === todayStr),
+  ];
+
+  if (!touched.length) {
+    console.log(dim(`Nothing tracked for today (${todayStr}).`));
+    return 0;
+  }
+
+  console.log(header(`Today — ${todayStr}`));
+  for (const x of touched) {
+    const type = 'number' in x ? 'project' : 'work';
+    const name = x.title || x.name || x.id;
+    const markers = [];
+    if (x.created === todayStr) markers.push('created');
+    if (x.shipped === todayStr) markers.push('shipped');
+    if (x.updated === todayStr && x.updated !== x.created) markers.push('updated');
+    console.log(`  ${statusBadge(x.status)} ${name} ${dim(`[${type}] ${markers.join(', ')}`)}`);
+  }
+  console.log('');
+  return 0;
+}

package/dist/engineering-pa-core/src/desk/format.mjs

@@ -0,0 +1,84 @@
+// desk — terminal output formatting
+// ANSI colour palette for developer CLI output.
+
+const C = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  red: '\x1b[38;5;210m',
+  green: '\x1b[38;5;150m',
+  yellow: '\x1b[38;5;222m',
+  blue: '\x1b[38;5;110m',
+  cyan: '\x1b[38;5;117m',
+  purple: '\x1b[38;5;183m',
+  orange: '\x1b[38;5;215m',
+  grey: '\x1b[38;5;245m',
+};
+
+const USE_COLOUR = process.stdout.isTTY && !process.env.NO_COLOR;
+
+export function colour(c, s) {
+  if (!USE_COLOUR) return s;
+  return `${C[c] || ''}${s}${C.reset}`;
+}
+
+export function bold(s) { return colour('bold', s); }
+export function dim(s) { return colour('dim', s); }
+
+export const STATUS_COLOURS = {
+  'in-progress': 'cyan',
+  blocked: 'red',
+  planned: 'yellow',
+  draft: 'grey',
+  done: 'green',
+  archived: 'dim',
+};
+
+export const CATEGORY_COLOURS = {
+  feature: 'cyan',
+  bug: 'red',
+  techDebt: 'orange',
+  discussion: 'purple',
+  chore: 'grey',
+  research: 'blue',
+};
+
+export function statusBadge(status) {
+  const col = STATUS_COLOURS[status] || 'grey';
+  return colour(col, `[${status}]`);
+}
+
+export function categoryBadge(category) {
+  if (!category) return '';
+  const col = CATEGORY_COLOURS[category] || 'grey';
+  return colour(col, category);
+}
+
+export function priorityLabel(p) {
+  if (p == null) return dim('—');
+  if (p === 0) return colour('red', 'P0');
+  if (p === 1) return colour('orange', 'P1');
+  if (p === 2) return colour('yellow', 'P2');
+  return dim(`P${p}`);
+}
+
+export function truncate(s, n) {
+  if (!s) return '';
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + '…';
+}
+
+export function padEnd(s, n) {
+  // ANSI-aware padding. Strip ANSI for length computation.
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, '');
+  const pad = Math.max(0, n - visible.length);
+  return s + ' '.repeat(pad);
+}
+
+export function header(title) {
+  return '\n' + bold(colour('purple', title)) + '\n' + dim('─'.repeat(Math.max(20, title.length))) + '\n';
+}
+
+export function kv(key, value) {
+  return `  ${dim(key.padEnd(12))} ${value}`;
+}

package/dist/engineering-pa-core/src/desk/repo.mjs

@@ -0,0 +1,172 @@
+// desk — repo walker
+// Source of truth: projects/{id}/project.json + work/{id}.json.
+// Walks the operator repo on every call. No caching. No stale state.
+//
+// Repo root discovery:
+//   1. DAVE_REPO_ROOT or PA_REPO_ROOT env var (explicit override).
+//   2. `.git`-walk upwards from process.cwd().
+//
+// The v1 pattern of `resolve(__dirname, '../../../..')` is intentionally not
+// used. In v2 the package lives in `node_modules/@stravica-ai/engineering-pa-core/`
+// inside the operator repo — `__dirname`-relative navigation would land outside
+// the operator's tree, not at its root.
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch {
+    return 'missing';
+  }
+}
+
+/**
+ * Walk up from `start` looking for a `.git` entry. Returns the first
+ * directory that contains one, or null. A `.git` *file* (worktree) is
+ * accepted alongside a `.git` *directory* (primary checkout) — both mark
+ * the top of an operator repo.
+ */
+export async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const kind = await pathKind(join(d, '.git'));
+    if (kind === 'dir' || kind === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+let _repoRootPromise = null;
+async function resolveRepoRoot() {
+  if (_repoRootPromise) return _repoRootPromise;
+  _repoRootPromise = (async () => {
+    const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+    if (envRoot) return resolve(envRoot);
+    const found = await findRepoRoot(process.cwd());
+    if (!found) {
+      const err = new Error(
+        'could not find operator repo root from ' + process.cwd() +
+        ' (no .git ancestor; set DAVE_REPO_ROOT or PA_REPO_ROOT to override)'
+      );
+      err.exitCode = 2;
+      throw err;
+    }
+    return found;
+  })();
+  return _repoRootPromise;
+}
+
+// Cached, lazy. Exposed as a getter so consumers can await it; tests can
+// override via _resetRepoRoot() + DAVE_REPO_ROOT.
+export async function getRepoRoot() {
+  return resolveRepoRoot();
+}
+
+// Test seam: allow tests to reset the cached repo root between cases.
+export function _resetRepoRoot() {
+  _repoRootPromise = null;
+}
+
+export async function readJson(path) {
+  const raw = await readFile(path, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function listProjects() {
+  const repoRoot = await getRepoRoot();
+  const projectsDir = join(repoRoot, 'projects');
+  let entries;
+  try {
+    entries = await readdir(projectsDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const projects = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = join(projectsDir, entry.name, 'project.json');
+    try {
+      const project = await readJson(manifestPath);
+      projects.push(project);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw new Error(`bad project manifest at ${manifestPath}: ${err.message}`);
+      }
+    }
+  }
+  return projects;
+}
+
+export async function getProject(id) {
+  const repoRoot = await getRepoRoot();
+  const manifestPath = join(repoRoot, 'projects', id, 'project.json');
+  try {
+    return await readJson(manifestPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function listWork() {
+  const repoRoot = await getRepoRoot();
+  const workDir = join(repoRoot, 'work');
+  let entries;
+  try {
+    entries = await readdir(workDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const items = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const path = join(workDir, entry.name);
+    try {
+      const item = await readJson(path);
+      items.push(item);
+    } catch (err) {
+      throw new Error(`bad work manifest at ${path}: ${err.message}`);
+    }
+  }
+  return items;
+}
+
+export async function getWork(id) {
+  const repoRoot = await getRepoRoot();
+  const path = join(repoRoot, 'work', `${id}.json`);
+  try {
+    return await readJson(path);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// Sort orders used by multiple commands.
+export const STATE_ORDER = [
+  'in-progress',
+  'blocked',
+  'planned',
+  'draft',
+  'done',
+  'archived',
+];
+
+export function sortByStateThenPriority(items) {
+  return items.slice().sort((a, b) => {
+    const sa = STATE_ORDER.indexOf(a.status || 'draft');
+    const sb = STATE_ORDER.indexOf(b.status || 'draft');
+    if (sa !== sb) return sa - sb;
+    const pa = a.priority == null ? 99 : a.priority;
+    const pb = b.priority == null ? 99 : b.priority;
+    if (pa !== pb) return pa - pb;
+    return (a.id || '').localeCompare(b.id || '');
+  });
+}