create-pmos 0.13.0 → 0.15.0

package/workspace/lib/profiles.js

@@ -0,0 +1,285 @@
+'use strict';
+/*
+ * Claude profile descriptors — a PURE reader (initiative `workspace-profiles`, PRD R1/R2/R4/R6/R7).
+ *
+ * The workspace lets the PM name a profile when a session's process is created. This module is the
+ * half of that feature which decides WHAT IS TRUE: it reads `<home>/.claude/profiles/*.json` and
+ * reports what it found. It never spawns anything, never writes, and never touches the network.
+ *
+ * WHAT THIS MODULE IS NOT ALLOWED TO IMPLY. PMOS holds no credential, runs no MCP client, and
+ * cannot ask a running `claude` what configuration it is really using. So every value here is
+ * "what a file on this machine declares", never "what is true of the world". The naming below is
+ * deliberately clumsy in places (`declared`, `recorded`) because the shorter words all read as
+ * verified facts.
+ *
+ * HONESTY BY CONSTRUCTION — readProfiles() returns a FOUR-way discrimination, not a boolean.
+ * These are four different facts about the world and collapsing any pair of them produces a
+ * specific, known lie:
+ *
+ *   { ok:true,  absent:true,  profiles:[],    broken:[]   }  no ~/.claude/profiles directory.
+ *        A calm, stated absence. Nothing was read because there was nothing to read. The picker
+ *        renders the path and says so. It must NOT render `work`/`personal` chips: those are the
+ *        names the PM's machine is expected to carry, not names PMOS ships, and drawing them here
+ *        is the PRD's stated FAIL — a picker appears, a choice is made, and nothing was applied.
+ *
+ *   { ok:true,  absent:false, profiles:[],    broken:[]   }  the directory exists and is empty.
+ *        A SUCCESSFUL READ OF NOTHING. Same consequence for the PM, different fact: the directory
+ *        was created and left empty rather than never created. Calm, not red.
+ *
+ *   { ok:true,  absent:false, profiles:[…],   broken:[…]  }  some descriptors read, some did not.
+ *        R4: one bad file must not take the others down. The good ones are still offered; each bad
+ *        one is named with its filename and its reason so it renders RED. Note that `profiles` can
+ *        be EMPTY while `broken` is not — every descriptor on the machine is malformed. A consumer
+ *        that tests only `profiles.length` renders that as the calm empty state above, which
+ *        reports a failure as an emptiness. Check `broken.length` before drawing calm prose.
+ *
+ *   { ok:false, absent:false, profiles:[],    error:'…'   }  the directory could not be read.
+ *        Permissions, or a FILE sitting where the directory should be. This is the distinction the
+ *        module exists to protect: a missing directory and an unreadable one are different facts.
+ *        Defaulting an unreadable directory to "no profiles configured" would state a capability
+ *        claim the data does not support — it would tell the PM their machine has no profiles when
+ *        what actually happened is that PMOS could not look.
+ *
+ * `dir` is returned in every case, including the failures, because R2 and R10 both require the
+ * surface to NAME the path it read or failed to read. An absence with no path is an assertion the
+ * PM cannot check.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// Where the agent CLI keeps them. PMOS does not define this format and never writes here (PRD
+// non-goal 3) — it is read-only to us, so an unexpected key is ignored rather than migrated.
+const PROFILE_SUBDIR = ['.claude', 'profiles'];
+
+function profilesDir(homeDir) { return path.join(homeDir, ...PROFILE_SUBDIR); }
+
+// Errors are shown to a human who has to go fix a file, so carry the code AND the message. Both
+// halves earn their place: the code says what kind of problem it is, the message says which path.
+// Node already prefixes most fs messages with the code, so only prepend it when it is missing —
+// "EISDIR: EISDIR: illegal operation" is noise in a line a PM is meant to act on.
+function describeErr(e) {
+  const msg = String((e && e.message) || e);
+  const code = e && e.code ? String(e.code) : '';
+  return (code && !msg.startsWith(code) ? `${code}: ${msg}` : msg).slice(0, 200);
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+/*
+ * Validate one parsed descriptor against R1's table. Returns `{ profile }` or `{ error }`.
+ *
+ * The rule running through every branch: A KEY THAT IS PRESENT BUT WRONG-TYPED MAKES THE
+ * DESCRIPTOR UNREADABLE. It is never coerced and never dropped. The reason is that both softer
+ * options lie in the PM's favour. Coercing `mcp: "jira"` into `["jira"]` invents a declaration the
+ * file did not make; dropping it renders "no mcp servers declared in this profile" over a file
+ * that plainly declared one. Rejecting is loud, names the file, and leaves the other descriptors
+ * alone (R4) — the PM gets a fixable error instead of a quiet wrong answer.
+ *
+ * A key that is ABSENT is a different matter: R1 forbids substituting a default, so absence is
+ * carried through as `null` (account) or `[]` (mcp) for the consumer to state, not to fill in.
+ */
+function validate(raw, stem) {
+  if (!isPlainObject(raw)) {
+    const found = raw === null ? 'null' : Array.isArray(raw) ? 'an array' : typeof raw;
+    return { error: `is not a JSON object — found ${found}` };
+  }
+
+  // `id` is the identity the pane line, the session record and the descriptor path all cite, so it
+  // is the one key with no tolerated absence. Falling back to the filename stem would look
+  // harmless and be exactly the wrong thing: PMOS would be manufacturing the identity it then
+  // displays as read from the file, and a later rename would silently change which profile a
+  // session claims to have run under.
+  if (!has(raw, 'id')) {
+    return { error: 'declares no `id` — PMOS will not substitute the filename, because the id is the identity the pane and the session record cite' };
+  }
+  if (typeof raw.id !== 'string' || !raw.id) return { error: '`id` is present but is not a non-empty string' };
+  if (raw.id !== stem) {
+    return { error: `declares id "${raw.id}" but is filed as ${stem}.json — the descriptor's identity disagrees with its filename` };
+  }
+
+  let label = raw.id;                       // R1: display name, falls back to `id` when absent
+  if (has(raw, 'label')) {
+    if (typeof raw.label !== 'string' || !raw.label.trim()) return { error: '`label` is present but is not a non-empty string' };
+    label = raw.label;
+  }
+
+  // Displayed VERBATIM and always attributed to the file (R1). PMOS cannot verify an account
+  // string and does not try; if it is wrong on disk it is wrong on screen, which is why every
+  // surface that shows it also shows where it came from. Absent stays null — "not declared" is a
+  // thing the consumer can say, and is not the same as an empty account name.
+  let account = null;
+  if (has(raw, 'account')) {
+    if (typeof raw.account !== 'string') return { error: '`account` is present but is not a string' };
+    account = raw.account;
+  }
+
+  // R7: these are names a file declares, never servers PMOS reached. Absent and `[]` collapse to
+  // the same array on purpose — both mean "this descriptor declares no MCP servers", which is one
+  // fact with one honest phrasing. What must NOT collapse into it is a malformed `mcp`, above.
+  let mcp = [];
+  if (has(raw, 'mcp')) {
+    if (!Array.isArray(raw.mcp) || raw.mcp.some((x) => typeof x !== 'string')) {
+      return { error: '`mcp` is present but is not an array of server names' };
+    }
+    mcp = raw.mcp.slice();
+  }
+
+  // The only key with a mechanical effect: it becomes the environment overlay at process creation
+  // (R3). `null` (key absent) and `{}` (declared empty) are kept DISTINCT here even though both
+  // apply nothing, because the reader's job is to report the file faithfully; profileLine() is
+  // where they converge, and it converges them on the sentence that says nothing was applied.
+  let env = null;
+  if (has(raw, 'env')) {
+    if (!isPlainObject(raw.env)) return { error: '`env` is present but is not an object of environment variables' };
+    for (const k of Object.keys(raw.env)) {
+      if (typeof raw.env[k] !== 'string') {
+        return { error: `\`env.${k}\` is not a string — PMOS will not coerce a value into an environment variable it was not given` };
+      }
+    }
+    env = { ...raw.env };
+  }
+
+  return { profile: { id: raw.id, label, account, mcp, env } };
+}
+
+/*
+ * Read every descriptor under `<homeDir>/.claude/profiles`.
+ *
+ * `homeDir` is a parameter rather than `os.homedir()` read inside, which is what makes this
+ * testable against real fixture directories instead of against a mock of the filesystem. A caller
+ * with no home directory gets a stated failure; guessing one would be the same class of invention
+ * this whole module refuses.
+ */
+function readProfiles(homeDir) {
+  if (typeof homeDir !== 'string' || !homeDir) {
+    return {
+      ok: false, absent: false, dir: null, profiles: [], broken: [],
+      error: 'no home directory was given — PMOS will not guess where .claude/profiles lives',
+    };
+  }
+  const dir = profilesDir(homeDir);
+
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (e) {
+    // THE DISTINCTION THIS MODULE EXISTS FOR. ENOENT is "there is nothing here", which is calm and
+    // true. Everything else — EACCES, ENOTDIR, EIO — is "PMOS could not look", which is a failure
+    // and must read red. Reporting the second as the first would tell the PM their machine has no
+    // profiles configured when PMOS never got far enough to know.
+    if (e && e.code === 'ENOENT') return { ok: true, absent: true, dir, profiles: [], broken: [], error: null };
+    if (e && e.code === 'ENOTDIR') {
+      return { ok: false, absent: false, dir, profiles: [], broken: [], error: `${dir} is not a directory — a file is sitting where the profiles directory should be` };
+    }
+    return { ok: false, absent: false, dir, profiles: [], broken: [], error: `${dir} could not be read — ${describeErr(e)}` };
+  }
+
+  const profiles = [];
+  const broken = [];
+  // Sorted so the picker's chip order is stable across reads. Directory order is not.
+  for (const name of names.slice().sort()) {
+    if (!name.endsWith('.json')) continue;     // not a descriptor at all — not a failed one either
+    const file = path.join(dir, name);
+    const stem = name.slice(0, -'.json'.length);
+
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      // Includes EISDIR: a DIRECTORY named `something.json`. Reported rather than skipped — it
+      // occupies the name a descriptor would have, so silently passing over it would leave the PM
+      // looking at a picker missing a chip with nothing anywhere saying why.
+      broken.push({ file: name, path: file, error: `could not be read — ${describeErr(e)}` });
+      continue;
+    }
+
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch (e) {
+      broken.push({ file: name, path: file, error: `is not valid JSON — ${String((e && e.message) || e).slice(0, 140)}` });
+      continue;
+    }
+
+    const v = validate(raw, stem);
+    if (v.error) { broken.push({ file: name, path: file, error: v.error }); continue; }
+    profiles.push({ ...v.profile, path: file });
+  }
+
+  // ok:true means THE DIRECTORY was read. It does not mean every file in it was. R4 requires those
+  // to be separable, so a malformed descriptor lands in `broken` and leaves its neighbours usable.
+  return { ok: true, absent: false, dir, profiles, broken, error: null };
+}
+
+/*
+ * The one line naming what a pane is running under — PRD R6, verbatim sentences.
+ *
+ * DIVERGENCE FROM THE DESIGN, recorded rather than glossed. `HANDOFF.md` §3 asks for
+ * `profile: claude-work · mcp: jira confluence slack gworkspace`, and `mcp: none` for the other
+ * case. This returns the PRD's R6/R7 wording instead, for two reasons the PRD states and the
+ * design does not address:
+ *   - `mcp: none` reads as a checked fact about the world. PMOS has no MCP client and never
+ *     contacted anything; the only thing it knows is what the descriptor declared. R7 forbids the
+ *     phrase outright, and the honest replacement is "no mcp servers declared in this profile".
+ *   - the design's line has no way to say "the profile declares no environment overlay", which is
+ *     the case where the PM is most likely to believe a choice took effect when nothing did.
+ * If the literal design string is wanted it is a PM ruling, not an implementation detail.
+ *
+ * "applied N environment variables" IS A CLAIM ABOUT THE SPAWN, not about the file. This function
+ * is a formatter and cannot verify it. The caller must therefore only pass a descriptor for a
+ * session PMOS actually created with that descriptor's overlay (R3); rendering this line from a
+ * descriptor that was merely selected would state an application that never happened.
+ *
+ * The three no-descriptor cases are distinguished by the ARGUMENT'S OWN TYPE, because they survive
+ * a JSON round-trip differently and a session record is JSON:
+ *   undefined / key absent → "not recorded"     (an orphan tmux pane, or a record persisted before
+ *                                                this feature existed — inventing a profile for it
+ *                                                would be a lie about the past)
+ *   null                   → "none was chosen"  (PMOS started it and recorded that nothing was
+ *                                                picked; `null` is written explicitly so it does
+ *                                                not decay into the case above)
+ * A bare id STRING is rejected on purpose: what was applied is a fact about the descriptor, so a
+ * caller holding only an id must resolve it through readProfiles() first (R9 — a respawn whose
+ * descriptor has since been deleted must not substitute another).
+ */
+function profileLine(profile, read) {
+  if (profile === undefined) return 'profile: not recorded — PMOS did not start this pane';
+
+  if (profile === null) {
+    // Only claim the machine has none configured when the read in hand actually says so. A read
+    // that failed, or one that found broken descriptors, does not support that sentence — the
+    // profiles may well be there and unreadable.
+    const noneConfigured = !!read && read.ok === true &&
+      (read.absent === true ||
+        ((read.profiles || []).length === 0 && (read.broken || []).length === 0));
+    return noneConfigured
+      ? 'no profile — none was chosen (no profiles are configured on this machine)'
+      : 'no profile — none was chosen for this session';
+  }
+
+  if (!isPlainObject(profile)) return 'profile: unreadable — the recorded value is not a profile descriptor';
+
+  // `label` is the declared display name (R1) but `id` is the traceable one: it is the descriptor's
+  // filename stem, so a reader can go check the file. Label wins where present because the spec
+  // says so; where it is absent the id carries the line.
+  const name = (typeof profile.label === 'string' && profile.label) ? profile.label
+    : (typeof profile.id === 'string' && profile.id) ? profile.id : null;
+  if (!name) return 'profile: unreadable — the recorded descriptor names no profile';
+
+  const n = isPlainObject(profile.env) ? Object.keys(profile.env).length : 0;
+  if (n === 0) {
+    // Covers both "no `env` key" and "`env: {}`". They differ on disk and are identical to the PM:
+    // nothing was applied. Saying "applied 0 environment variables" would be the precise phrasing
+    // most likely to be read as success, so R6 replaces it with a sentence about consequence.
+    return `profile: ${name} — the profile declares no environment overlay; this session runs with the workspace's default environment`;
+  }
+
+  const vars = `applied ${n} environment variable${n === 1 ? '' : 's'}`;
+  const mcp = (Array.isArray(profile.mcp) && profile.mcp.length)
+    ? `mcp declared by the profile: ${profile.mcp.join(' ')}`
+    : 'no mcp servers declared in this profile';
+  return `profile: ${name} — ${vars} · ${mcp}`;
+}
+
+module.exports = { readProfiles, profileLine, profilesDir, PROFILE_SUBDIR };