@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/cockpit/cockpit-card-feedback-store.ts

@@ -21,11 +21,19 @@
  *                     closed item rather than returning to the person's queue;
  *   · a receipt for another `feedbackId` changes nothing.
  *
- * The file is CloudCLI's own state, not the provider's: the default path is
- * `~/.cloudcli/cockpit-card-feedback.json`; a criterion passes its own path, and `null` keeps
- * the store in memory (the composition root decides which one a boot gets).
+ * The file is Cloudpit's own state, not the provider's: the default path is
+ * `~/.cloudcli/cockpit-card-feedback.json` through 2.x; a criterion passes its own path, and
+ * `null` keeps the store in memory (the composition root decides which one a boot gets).
+ *
+ * 2.1 URI-KEY NORMALIZATION. Every persisted string that still starts with `cloudcli://` — the
+ * overlay `params`/`outcome`/card record fields as well as any nested `subject.uri` — is
+ * rewritten to `cloudpit://` when the store reads the file, and the rewritten document is
+ * written back after copying the pre-normalization file to `<file>.cloudcli-backup`. The rewrite
+ * is idempotent (a second store finds nothing to change), it never drops an overlay or notice,
+ * and a failed write restores/keeps the original file and reports the reason through
+ * {@link CockpitCardFeedbackStore.normalization}. Reads are normalized either way.
  */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import type {
@@ -105,6 +113,8 @@ export type CockpitCardFeedbackStore = {
   applyCards(cards: readonly CockpitCard[]): CockpitCard[];
   /** The wire reading of one stored overlay. */
   feedbackOf(record: StoredCockpitCardFeedback): CockpitCardFeedback;
+  /** The 2.1 URI-key normalization reading for this store's file (see the module header). */
+  normalization(): CockpitCardFeedbackNormalization;
   dispose(): void;
 };
 
@@ -114,6 +124,18 @@ type PersistedState = {
   notices?: unknown;
 };
 
+/**
+ * What the 2.1 URI-key normalization did when this store read its file. `changed` is true only
+ * in the store whose construction rewrote at least one `cloudcli://` string; `backupPath` names
+ * the pre-normalization copy; `error` is set when the rewrite could not be persisted, in which
+ * case the original file is kept on disk (and reads are still normalized in memory).
+ */
+export type CockpitCardFeedbackNormalization = {
+  changed: boolean;
+  backupPath: string | null;
+  error: string | null;
+};
+
 /** Whether a provider's answer names a disposition this lifecycle knows. */
 function isDisposition(value: string): value is CockpitCardReceipt['disposition'] {
   return (
@@ -212,6 +234,39 @@ export function readCockpitCardReceipt(value: unknown): CockpitCardReceipt | nul
   };
 }
 
+/**
+ * Rewrites every persisted string VALUE that starts with `cloudcli://` to `cloudpit://`, walking
+ * arrays and nested records (an overlay's `params`, a card record's `subject.uri`, …). Object
+ * keys are left alone: an address is data here, never a lookup key. Returns the input unchanged
+ * when there was nothing to rewrite, so a second read is a no-op.
+ */
+function normalizeUriStrings(value: unknown): { value: unknown; changed: boolean } {
+  if (typeof value === 'string') {
+    return value.startsWith('cloudcli://')
+      ? { value: `cloudpit://${value.slice('cloudcli://'.length)}`, changed: true }
+      : { value, changed: false };
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map((item) => {
+      const result = normalizeUriStrings(item);
+      changed = changed || result.changed;
+      return result.value;
+    });
+    return { value: changed ? items : value, changed };
+  }
+  const entry = record(value);
+  if (entry === null) return { value, changed: false };
+  let changed = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(entry)) {
+    const result = normalizeUriStrings(item);
+    changed = changed || result.changed;
+    next[key] = result.value;
+  }
+  return { value: changed ? next : value, changed };
+}
+
 /**
  * Builds one store. `filePath === null` keeps it in memory; otherwise a corrupt or missing file
  * is an empty store (never a boot failure), and every mutation rewrites it atomically enough for
@@ -223,16 +278,55 @@ export function createCockpitCardFeedbackStore(options: {
   const filePath = options.filePath ?? null;
   const overlays = new Map<string, StoredCockpitCardFeedback>();
   const notices = new Map<string, CockpitCardFeedbackNotice>();
+  let normalization: CockpitCardFeedbackNormalization = {
+    changed: false,
+    backupPath: null,
+    error: null,
+  };
 
   if (filePath !== null) {
     try {
-      const parsed = JSON.parse(readFileSync(filePath, 'utf8')) as PersistedState;
-      for (const raw of Array.isArray(parsed.overlays) ? parsed.overlays : []) {
-        const overlay = readOverlay(raw);
+      const raw = readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw) as unknown;
+      const normalized = normalizeUriStrings(parsed);
+      // Reads are normalized even when the rewrite cannot be persisted: the legacy spelling is
+      // an accepted input, not the object's current address.
+      const state: PersistedState = record(normalized.value) ?? {};
+      const existingBackup = `${filePath}.cloudcli-backup`;
+      if (normalized.changed) {
+        try {
+          mkdirSync(path.dirname(filePath), { recursive: true });
+          // Keep the FIRST pre-normalization copy: a later run must not overwrite the pristine
+          // ledger with an already-normalized file.
+          if (!existsSync(existingBackup)) writeFileSync(existingBackup, raw, 'utf8');
+          writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+          normalization = { changed: true, backupPath: existingBackup, error: null };
+        } catch (error) {
+          // The original file wins: a failed rewrite leaves it byte-identical and reports why.
+          try {
+            writeFileSync(filePath, raw, 'utf8');
+          } catch {
+            // A read-only home keeps the in-memory (normalized) reading; the report says so.
+          }
+          normalization = {
+            changed: false,
+            backupPath: existsSync(existingBackup) ? existingBackup : null,
+            error: error instanceof Error ? error.message : 'the URI-key normalization write failed',
+          };
+        }
+      } else {
+        normalization = {
+          changed: false,
+          backupPath: existsSync(existingBackup) ? existingBackup : null,
+          error: null,
+        };
+      }
+      for (const rawOverlay of Array.isArray(state.overlays) ? state.overlays : []) {
+        const overlay = readOverlay(rawOverlay);
         if (overlay !== null) overlays.set(overlay.cardId, overlay);
       }
-      for (const raw of Array.isArray(parsed.notices) ? parsed.notices : []) {
-        const notice = readNotice(raw);
+      for (const rawNotice of Array.isArray(state.notices) ? state.notices : []) {
+        const notice = readNotice(rawNotice);
         if (notice !== null) notices.set(notice.cardId, notice);
       }
     } catch {
@@ -382,6 +476,7 @@ export function createCockpitCardFeedbackStore(options: {
       });
     },
     feedbackOf,
+    normalization: () => normalization,
     dispose: () => persist(),
   };
 }

package/server/modules/cockpit/cockpit-card-registry.ts

@@ -29,7 +29,7 @@
  * The action channel reads the same projection (`getCard`), so a confirmation can
  * only act on a card the registry currently shows, and the provider's declared
  * executor set is the union of its providers' declarations plus the two built-in
- * content-default executors (they are CloudCLI's own, not any provider's).
+ * content-default executors (they are Cloudpit's own, not any provider's).
  *
  * A new provider is one implementation plus one `register` (or one element in the
  * constructor array); no call site in the cockpit changes.
@@ -246,7 +246,7 @@ export function createCockpitCardRegistry(
   for (const provider of providers) register(provider);
 
   const declaredExecutors = (): ReadonlySet<string> => {
-    // The two built-in executors are CloudCLI's own content defaults; no provider
+    // The two built-in executors are Cloudpit's own content defaults; no provider
     // declares them, yet every card whose subject names a session/project reaches
     // them, so the declared set must include them or the action channel would
     // refuse the very defaults this projection fills in.

package/server/modules/cockpit/cockpit-fleet-card-projection.ts

@@ -639,6 +639,9 @@ function mapCard(
   // The knowledge case is a PROVIDER statement: readable evidence passes through verbatim and
   // an unreadable block is simply absent. The cockpit adds nothing here; the confirmation
   // authority stamps its signed reference on a later read (see `cockpit-knowledge-decision.ts`).
+  // The entry's title and statement are part of that same passthrough: `readKnowledgeCase`
+  // reads them verbatim and omits them when the provider states none, so this mapping needs no
+  // branch of its own.
   const knowledge = readKnowledgeCase(raw.knowledge);
 
   const card: CockpitCard = {

package/server/modules/cockpit/cockpit-fleet-executor.ts

@@ -5,7 +5,7 @@
  * WHY THE IDS COME FROM THE CLI. The fleet owns the executor surface: `rescue executors --json`
  * answers `{ ok, executors: [{ id, action, does, params }] }`, and the four ids it currently
  * ships (`fleet.hold`, `fleet.park`, `fleet.redispatch`, `fleet.log`) are that document's
- * content, not a CloudCLI constant. Hard-coding them here would drift the moment the fleet adds
+ * content, not a Cloudpit constant. Hard-coding them here would drift the moment the fleet adds
  * or renames one, and a declaration the consumer cannot see is exactly the failure this task
  * exists to remove. This module therefore PARSES the declaration and instantiates one executor
  * per entry; nothing below names an id except `fleet.log`, which the own-reply contract names.

package/server/modules/cockpit/cockpit-knowledge-reading.ts

@@ -54,6 +54,19 @@ function text(value: unknown): string {
   return typeof value === 'string' ? value : '';
 }
 
+/**
+ * A provider-stated display string, kept BYTE FOR BYTE when it has visible content.
+ *
+ * Unlike the identity fields (which are trimmed because they are compared), a title/statement
+ * is shown to the person and may be a Markdown body whose whitespace is significant. Returning
+ * it verbatim keeps the card's text exactly the provider's word; a value with no visible
+ * content is treated as unstated so the block omits the key entirely.
+ */
+function statedText(value: unknown): string {
+  const raw = text(value);
+  return raw.trim() === '' ? '' : raw;
+}
+
 function nonNegativeInteger(value: unknown): number | null {
   return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
 }
@@ -132,6 +145,8 @@ export function readKnowledgeCase(value: unknown): CockpitKnowledgeCase | null {
   const progress = readProgress(value.progress);
   const verification = readVerification(value.verification);
   const knowledgeId = text(value.knowledgeId).trim();
+  const title = statedText(value.title);
+  const statement = statedText(value.statement);
   const executionId = text(value.executionId).trim();
   const nextCheckAt = text(value.nextCheckAt).trim();
   const originSessionId = text(value.originSessionId).trim();
@@ -146,6 +161,8 @@ export function readKnowledgeCase(value: unknown): CockpitKnowledgeCase | null {
       ? (state as CockpitKnowledgeCaseState)
       : 'unknown',
     ...(knowledgeId === '' ? {} : { knowledgeId }),
+    ...(title === '' ? {} : { title }),
+    ...(statement === '' ? {} : { statement }),
     ...(plan === null ? {} : { plan }),
     ...(progress === undefined ? {} : { progress }),
     ...(executionId === '' ? {} : { executionId }),

package/server/modules/cockpit/cockpit.module.ts

@@ -79,7 +79,7 @@ export type CockpitCardsModuleDeps = {
   fixtureFeedback?: Partial<CockpitFixtureFeedbackSettings>;
   /**
    * Where the feedback overlay persists. Omitted keeps it in memory — which is what a criterion
-   * wants; `server/index.ts` passes CloudCLI's own file so a refresh/restart keeps the overlay.
+   * wants; `server/index.ts` passes Cloudpit's own file so a refresh/restart keeps the overlay.
    */
   feedbackFilePath?: string | null;
   /** A store the caller already built (a criterion reads it after a request). */
@@ -269,7 +269,7 @@ export function createCockpitCardsModule(deps: CockpitCardsModuleDeps): CockpitC
     fixtureBriefFor = fixture.brief;
   }
 
-  // The feedback overlay is CloudCLI's own lifecycle state. It is built here, once per module,
+  // The feedback overlay is Cloudpit's own lifecycle state. It is built here, once per module,
   // so both the read route and the resend command reach the same one.
   const feedbackStore =
     deps.feedbackStore ??

package/server/modules/cockpit/cockpit.reducer.ts

@@ -56,7 +56,7 @@ export type CockpitVisibleSet = {
   focusables: CockpitFocusable[];
   /**
    * The project roster the display can address, so the hub can map a `quay://` project
-   * segment back to the CloudCLI project id the fleet registry is keyed by. Optional: a
+   * segment back to the Cloudpit project id the fleet registry is keyed by. Optional: a
    * report without it still contributes focusables; target resolution then fails honestly.
    */
   projects: CockpitVisibleProject[];

package/server/modules/cockpit/tests/cockpit-card-feedback.test.ts

@@ -22,7 +22,7 @@
  *     server/modules/cockpit/tests/cockpit-card-feedback.test.ts
  */
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
@@ -615,6 +615,121 @@ test('a resend reuses the same feedbackId and never runs the action again', asyn
   assert.equal(action.calls.length, 1, 'a resend never redoes the action');
 });
 
+test('2.1: reading a file with legacy URI strings normalizes them, backs up and is idempotent', () => {
+  const { directory, filePath } = storeFile();
+  try {
+    const pristine = {
+      overlays: [
+        {
+          cardId: 'card-legacy',
+          provider: 'test',
+          revision: 1,
+          feedbackId: 'feedback-legacy',
+          optionId: 'go',
+          label: 'Go ahead',
+          sentAt: AT,
+          outcome: { executor: 'test.action', ok: true },
+          feedbackExecutor: 'test.feedback',
+          params: {
+            attentionId: 'card-legacy',
+            subject: { uri: 'cloudcli://session/a' },
+            links: ['cloudcli://architecture/b', 'quay://proj/board'],
+          },
+        },
+      ],
+      notices: [
+        {
+          cardId: 'card-legacy',
+          feedbackId: 'feedback-legacy',
+          kind: 'kept',
+          ref: 'cloudcli://session/a#item-1',
+        },
+      ],
+      cardRecords: [
+        { id: 'card-legacy', subject: { uri: 'cloudcli://architecture/b' } },
+      ],
+    };
+    writeFileSync(filePath, `${JSON.stringify(pristine, null, 2)}\n`, 'utf8');
+
+    const first = createCockpitCardFeedbackStore({ filePath });
+    const reading = first.normalization();
+    assert.equal(reading.changed, true, 'the store reports that it rewrote legacy keys');
+    assert.equal(reading.error, null);
+    assert.equal(reading.backupPath, `${filePath}.cloudcli-backup`);
+    assert.ok(existsSync(reading.backupPath!), 'the pre-normalization copy exists');
+    assert.deepEqual(
+      JSON.parse(readFileSync(reading.backupPath!, 'utf8')),
+      pristine,
+      'the backup is the pristine file, not the rewritten one',
+    );
+
+    // No entry was lost, and every nested URI string (params, card records, notice refs) moved.
+    const overlay = first.overlay('card-legacy');
+    assert.ok(overlay, 'the overlay survives the rewrite');
+    assert.deepEqual(overlay.params.subject, { uri: 'cloudpit://session/a' });
+    assert.deepEqual(overlay.params.links, ['cloudpit://architecture/b', 'quay://proj/board'], 'non-cloud schemes stay verbatim');
+    assert.equal(first.notice('card-legacy')?.kind, 'kept', 'the notice survives the rewrite');
+
+    const rewritten = JSON.parse(readFileSync(filePath, 'utf8')) as {
+      notices: Array<{ ref: string }>;
+      cardRecords: Array<{ subject: { uri: string } }>;
+    };
+    assert.equal(rewritten.notices[0]!.ref, 'cloudpit://session/a#item-1');
+    assert.equal(rewritten.cardRecords[0]!.subject.uri, 'cloudpit://architecture/b');
+
+    // A second store finds nothing to normalize and does not overwrite the pristine backup.
+    const second = createCockpitCardFeedbackStore({ filePath });
+    assert.equal(second.normalization().changed, false, 'the normalization is idempotent');
+    assert.equal(second.normalization().error, null);
+    assert.deepEqual(
+      JSON.parse(readFileSync(reading.backupPath!, 'utf8')),
+      pristine,
+      'the first backup is still the pristine file',
+    );
+    assert.deepEqual(second.overlay('card-legacy')?.params.subject, { uri: 'cloudpit://session/a' });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('2.1: a failed normalization write keeps the original file and reports the reason', () => {
+  const { directory, filePath } = storeFile();
+  try {
+    const pristine = JSON.stringify({
+      overlays: [
+        {
+          cardId: 'card-legacy',
+          provider: 'test',
+          revision: 1,
+          feedbackId: 'feedback-legacy',
+          optionId: 'go',
+          label: 'Go ahead',
+          sentAt: AT,
+          outcome: { executor: 'test.action', ok: true },
+          feedbackExecutor: 'test.feedback',
+          params: { subject: { uri: 'cloudcli://session/a' } },
+        },
+      ],
+    });
+    writeFileSync(filePath, pristine, 'utf8');
+    chmodSync(filePath, 0o444);
+
+    const store = createCockpitCardFeedbackStore({ filePath });
+    const reading = store.normalization();
+    assert.equal(reading.changed, false, 'an unpersisted rewrite is not reported as changed');
+    assert.ok(reading.error, 'the failed write is reported');
+    assert.equal(readFileSync(filePath, 'utf8'), pristine, 'the original file is kept byte-identical');
+    assert.deepEqual(
+      store.overlay('card-legacy')?.params.subject,
+      { uri: 'cloudpit://session/a' },
+      'reads are normalized even when the file could not be rewritten',
+    );
+  } finally {
+    chmodSync(filePath, 0o644);
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
 test('a provider without a feedback executor answers an explicit unavailable reason', async () => {
   const provider = new MutableCardProvider([makeCard({ id: 'card-1' })], null);
   const registry = createCockpitCardRegistry([provider]);

package/server/modules/cockpit/tests/cockpit-fleet-card-provider.test.ts

@@ -583,14 +583,14 @@ test('AC-432: a session-ask card is filled from the digest, and its options answ
   assert.equal(
     fleet.provider.declaredExecutors().includes(COCKPIT_SESSION_SEND_EXECUTOR_ID),
     false,
-    'session.send is CloudCLI’s own content default, not a provider declaration',
+    'session.send is Cloudpit’s own content default, not a provider declaration',
   );
 });
 
 test('AC: a completed session-ask option answers its own session with 「label — does」', async () => {
   // Selecting an option on a session-ask card IS answering the assistant in that session: the
   // action is the ordinary `session.send`, addressed to the card's own session, and its text is
-  // the option name plus what choosing it does. `session.send` is CloudCLI's own declared
+  // the option name plus what choosing it does. `session.send` is Cloudpit's own declared
   // content default, so the registry must NOT mark these options unconfirmable.
   const reading: SessionAskDecisionReading = {
     state: 'evaluated',