n-seo 0.4.1 → 0.6.0

package/src/profile-report.ts

@@ -0,0 +1,108 @@
+/** What profile is active, and exactly where this instance departs from it.
+ *
+ *  The second half is the point. Someone running a client's portfolio on an
+ *  agency's method needs to see, at a glance, which numbers came from the
+ *  agency and which they changed themselves — otherwise "we follow your
+ *  model" is an unverifiable claim. */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  CONFIG_PATH, EXAMPLE_CONFIG_PATH, PROFILE_FILE, DEFAULT_RULES, DEFAULT_OPERATING_RULES,
+  ROOT, config, loadProfile, type Profile, type ProfilePrinciple,
+} from "./config.js";
+
+export interface Departure {
+  /** Dotted path, e.g. "rules.strikingDistance.maxRows". */
+  key: string;
+  /** What the layer beneath says: the profile, or the engine defaults. */
+  inherited: unknown;
+  /** What this instance sets instead. */
+  instance: unknown;
+}
+
+export interface ProfileReport {
+  /** The `profile` value from the config, if any. */
+  spec?: string;
+  name: string;
+  description?: string;
+  version?: string;
+  dir?: string;
+  departures: Departure[];
+  principles: ProfilePrinciple[];
+}
+
+/** Flatten a nested tree to dotted leaves, so two layers can be diffed. */
+function flatten(v: unknown, prefix = "", out: Record<string, unknown> = {}) {
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    for (const [k, val] of Object.entries(v)) flatten(val, prefix ? `${prefix}.${k}` : k, out);
+  } else if (prefix) {
+    out[prefix] = v;
+  }
+  return out;
+}
+
+function mergeDeep<T>(base: T, over: unknown): T {
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  if (over && typeof over === "object") {
+    for (const [k, v] of Object.entries(over as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      const cur = out[k];
+      out[k] = cur && typeof cur === "object" && v && typeof v === "object" && !Array.isArray(v)
+        ? mergeDeep(cur, v)
+        : v;
+    }
+  }
+  return out as T;
+}
+
+/** The config as written, not the normalized one. Normalization has already
+ *  merged the layers, so it can no longer say who set what. */
+function rawConfig(): Record<string, unknown> {
+  const p = fs.existsSync(CONFIG_PATH) ? CONFIG_PATH : EXAMPLE_CONFIG_PATH;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function profileReport(): ProfileReport {
+  const cfg = config();
+  const raw = rawConfig();
+  const loaded = cfg.profile ? loadProfile(cfg.profile) : null;
+  const profile = loaded?.profile ?? null;
+
+  const inherited = flatten({
+    rules: mergeDeep(DEFAULT_RULES, profile?.rules),
+    operatingRules: mergeDeep(DEFAULT_OPERATING_RULES, profile?.operatingRules),
+  });
+  const instanceSet = flatten({ rules: raw.rules, operatingRules: raw.operatingRules });
+
+  const departures = Object.entries(instanceSet)
+    .filter(([key, value]) => inherited[key] !== value)
+    .map(([key, value]) => ({ key, inherited: inherited[key], instance: value }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+
+  return {
+    spec: cfg.profile,
+    name: profile?.name ?? "engine defaults",
+    description: profile?.description,
+    version: profile?.version,
+    dir: loaded?.dir,
+    departures,
+    principles: (profile?.principles ?? []).filter((p) => p?.title && p?.body),
+  };
+}
+
+/** Profiles shipped with the engine. */
+export function builtinProfiles(): { spec: string; name: string; description?: string }[] {
+  const dir = path.join(ROOT, "profiles");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, PROFILE_FILE)))
+    .map((e) => {
+      const p = JSON.parse(fs.readFileSync(path.join(dir, e.name, PROFILE_FILE), "utf8")) as Profile;
+      return { spec: e.name, name: p.name || e.name, description: p.description };
+    })
+    .sort((a, b) => a.spec.localeCompare(b.spec));
+}

package/src/settings.tsx

@@ -7,6 +7,7 @@ import path from "node:path";
 import type { FC } from "hono/jsx";
 import { CONFIG_PATH, MODULE_INFO, config, saveConfig, USING_EXAMPLE_CONFIG, loadConfig, engineInfo } from "./config.js";
 import * as data from "./data.js";
+import { profileReport, builtinProfiles } from "./profile-report.js";
 
 const expand = (p: string) => (p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p);
 
@@ -32,6 +33,8 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
   const lr = data.lastRun();
   const eng = engineInfo();
   const upd = data.updateCheck();
+  const prof = profileReport();
+  const builtins = builtinProfiles();
   const hookCount = cfg.hooks.beforeRun.length + cfg.hooks.afterRun.length + Object.values(cfg.hooks.afterStep).reduce((n, l) => n + l.length, 0);
   const str = (v: unknown) => (v == null ? "" : String(v));
   return (
@@ -75,6 +78,44 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
             </p>
           )}
         </div>
+        <div class="s-card">
+          <div class="s-title">
+            Profile: {prof.name}{prof.version ? ` ${prof.version}` : ""}
+            {prof.departures.length > 0 && <span class="chip"> {prof.departures.length} override{prof.departures.length === 1 ? "" : "s"}</span>}
+          </div>
+          {prof.description && <p class="sub">{prof.description}</p>}
+          {!prof.spec && (
+            <p class="sub">
+              No profile set, so the engine defaults apply. Shipped with this engine:{" "}
+              {builtins.map((b, i) => <>{i > 0 ? ", " : ""}<code>{b.spec}</code></>)}. Set one with{" "}
+              <code>"profile"</code> in the config, or point it at a directory or an installed package.
+            </p>
+          )}
+          {prof.principles.length > 0 && (
+            <>
+              <p class="sub">{prof.principles.length} principle{prof.principles.length === 1 ? "" : "s"}, shown in full on <a href="/actions">Actions</a>.</p>
+              <ul class="prof-princ">
+                {prof.principles.map((pr) => (
+                  <li><span class={`chip ${pr.kind === "hard" ? "bad" : ""}`}>{pr.kind === "hard" ? "hard" : "guide"}</span> {pr.title}</li>
+                ))}
+              </ul>
+            </>
+          )}
+          {prof.departures.length > 0 && (
+            <>
+              <p class="sub">Changed here, against the {prof.spec ? "profile" : "engine defaults"}:</p>
+              <ul class="prof-diff">
+                {prof.departures.map((d) => (
+                  <li>
+                    <span class="mono">{d.key}</span>
+                    <span class="prof-was">{JSON.stringify(d.inherited)}</span>
+                    <span class="prof-now">{JSON.stringify(d.instance)}</span>
+                  </li>
+                ))}
+              </ul>
+            </>
+          )}
+        </div>
         <div class="s-card">
           <div class="s-title">Instance path</div>
           <div class="mono">{eng.instance}</div>

package/src/views.tsx

@@ -2,6 +2,7 @@
 import type { FC, PropsWithChildren } from "hono/jsx";
 import { SITES, ENGINE_VERSION, config, loadConfig, USING_EXAMPLE_CONFIG, type SiteCfg } from "./config.js";
 import * as data from "./data.js";
+import { profileReport } from "./profile-report.js";
 import { actionsFor, allActions, type Action } from "./actions.js";
 import { insights as loadInsights } from "./insights.js";
 
@@ -140,7 +141,18 @@ export const ActionModal: FC<{ a: Action; id: string }> = ({ a, id }) => (
       <span class={`chip effort e-${a.effort}`}>{effortLabel(a.effort, true)}</span>
       <span class="chip tag">{a.tag}</span>
       <span class="chip">{a.source === "backlog" ? "curated" : a.source === "proposal" ? "proposed" : "data-derived"}</span>
+      {a.priorityNotes?.length ? (
+        <span class="chip warn" title="a configured priority changed where this sits in the queue">reweighted</span>
+      ) : null}
     </div>
+    {a.priorityNotes?.length ? (
+      // The impact number decides the order, so a card whose number was
+      // adjusted has to say so on its face. Ordering you cannot see the
+      // reason for is ordering you cannot argue with.
+      <ul class="prio-notes">
+        {a.priorityNotes.map((n) => <li>{n}</li>)}
+      </ul>
+    ) : null}
     {a.watching && <p class="action-watching">⏳ {a.watching}</p>}
     <h4>Why (the data)</h4>
     <p>{a.why}</p>
@@ -265,6 +277,9 @@ const ProposalCard: FC<{ p: data.ScanOutput["proposals"][number]; index: number
 
 export const ActionsPage: FC<{ flash?: string }> = ({ flash }) => {
   const scan = data.opportunityScan();
+  const prof = profileReport();
+  const principles = prof.principles;
+  const profileName = prof.name;
   return (
     <>
       <div class="strip-head">
@@ -274,6 +289,21 @@ export const ActionsPage: FC<{ flash?: string }> = ({ flash }) => {
       <p class="sub">Data-derived rules (90-day window) + your curated queue (<code>config/backlog.json</code>). Click any item for the full spec. Impact numbers rank the queue — they are estimates for ordering, not forecasts.</p>
       {flash && <p class="flash">{flash}</p>}
 
+      {principles.length > 0 && (
+        <details class="wb-fold princ">
+          <summary>
+            Operating principles <small>— from the {profileName} profile; {principles.filter((p) => p.kind === "hard").length} are constraints, not advice</small>
+          </summary>
+          <div class="princ-list">
+            {principles.map((p) => (
+              <div class={`princ-item ${p.kind === "hard" ? "hard" : ""}`}>
+                <div class="princ-h"><span class={`chip ${p.kind === "hard" ? "bad" : ""}`}>{p.kind === "hard" ? "hard" : "guide"}</span> <b>{p.title}</b></div>
+                <p>{p.body}</p>
+              </div>
+            ))}
+          </div>
+        </details>
+      )}
       {scan && (scan.proposals.length > 0 || scan.verdicts.length > 0) && (
         <div class="scan-panel" id="proposed">
           <h2>Proposed by the opportunity scan <small>· {scan.generated} — rising queries no queue item covers, turned into candidate moves. Accepting copies a proposal into your queue; nothing self-modifies it.</small></h2>