Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

5.6 KB
Raw Blame
/**
 * The prompt stages PortOS features call by name — the single source of truth
 * for "which stage keys are system stages" (#3314).
 *
 * These stages are resolved by literal key (`getStage('cos-evaluate')`,
 * `runStage('brain-classifier')`, …) rather than authored by the user in the
 * Prompt Manager. Deleting one silently breaks the feature that names it, so
 * `DELETE /api/prompts/:stage` refuses without `?force=true`, and the Prompt
 * Manager badges + filters them.
 *
 * SCOPE: this is the CURATED set — the CoS / Brain / Memory / app-detection
 * stages the delete guard has always covered — and it is what the UI badges
 * and filters. It is NOT an exhaustive index of every literal-key call site:
 * roughly 100 of the 127 shipped stages are resolved by literal key too, and
 * badging all of them would make the SYSTEM badge and the "System only" filter
 * meaningless (#3335). Adding a row here means "this stage is now badged
 * SYSTEM", which is a deliberate choice per stage.
 *
 * Deletion protection is the OTHER half, and it is deliberately wider: the
 * generated `promptStageCallSites.generated.json` indexes every stage key a
 * `server/` source references, and `isProtectedStage()` unions it with this
 * table. So `pipeline-series-concept-judge` is undeletable without `?force=true`
 * while staying out of the badge. See `scripts/generate-prompt-stage-call-sites.js`.
 *
 * The map was previously restated three times — the usage handler's
 * `key -> usedBy[]` table, the DELETE guard's bare key array, and a client-side
 * `SYSTEM_STAGE_KEYS` mirror in `client/src/lib/promptStageGroups.js`. The
 * client copy could (and did) drift out of the server's, which after #3284 was
 * no longer cosmetic: a key missing from the client list made that stage
 * unreachable through the Stages pane's "System only" filter even though the
 * server would refuse to delete it. `GET /api/prompts` now ships the key list
 * so the client has nothing left to guess.
 *
 * Data + predicates, no toolkit dependency. The only read is the generated
 * call-site manifest, loaded once at module init.
 */

import { readFileSync } from 'node:fs';

/**
 * `stageKey -> human-readable feature names that call it`. The values are what
 * `GET /api/prompts/:stage/usage` surfaces as `usedBy` in the delete-confirm
 * dialog, so they read as UI copy rather than module paths.
 */
export const SYSTEM_STAGE_USAGE = Object.freeze({
  'cos-evaluate': Object.freeze(['CoS task evaluation']),
  'cos-report-summary': Object.freeze(['CoS daily reports']),
  'cos-self-improvement': Object.freeze(['CoS self-improvement tasks']),
  'cos-task-enhance': Object.freeze(['CoS task prompt enhancement']),
  'brain-classifier': Object.freeze(['Brain thought classification']),
  'brain-daily-digest': Object.freeze(['Brain daily digest generation']),
  'brain-weekly-review': Object.freeze(['Brain weekly review generation']),
  'memory-evaluate': Object.freeze(['Memory extraction from agent output']),
  'app-detection': Object.freeze(['Project directory analysis']),
});

/** Derived, never restated — the DELETE guard and the API response both read this. */
export const SYSTEM_STAGE_KEYS = Object.freeze(Object.keys(SYSTEM_STAGE_USAGE));

const SYSTEM_STAGE_SET = new Set(SYSTEM_STAGE_KEYS);

/** True when `key` names a stage a PortOS feature resolves by literal key. */
export function isSystemStage(key) {
  return SYSTEM_STAGE_SET.has(key);
}

/**
 * The feature names that call `key`, or an empty array for a user-authored
 * stage. Always an array so callers can render it without a null guard.
 *
 * Gated on the Set rather than indexing the object directly — a stage literally
 * named `toString` or `constructor` would otherwise resolve to an inherited
 * `Object.prototype` member and be reported as in-use.
 */
export function systemStageUsedBy(key) {
  return isSystemStage(key) ? SYSTEM_STAGE_USAGE[key] : [];
}

/**
 * `stageKey -> repo-relative source paths that reference it`, generated by
 * `scripts/generate-prompt-stage-call-sites.js` and drift-guarded by its test.
 * Read here rather than `import … with { type: 'json' }` so the module loads
 * identically under node, vitest, and any bundler in the chain.
 */
export const STAGE_CALL_SITES = Object.freeze(
  Object.fromEntries(
    Object.entries(
      JSON.parse(readFileSync(new URL('./promptStageCallSites.generated.json', import.meta.url), 'utf8')),
    ).map(([key, paths]) => [key, Object.freeze(paths)]),
  ),
);

const CALL_SITE_KEYS = new Set(Object.keys(STAGE_CALL_SITES));

const EMPTY = Object.freeze([]);

/**
 * The `server/` source files that name `key` as a string literal, or an empty
 * array when nothing does. Surfaced by `GET /api/prompts/:stage/usage` so the
 * delete-confirm dialog can name what breaks.
 *
 * Gated on the Set for the same reason `systemStageUsedBy` is — `toString`
 * must not resolve through `Object.prototype`.
 */
export function stageReferencedBy(key) {
  return CALL_SITE_KEYS.has(key) ? STAGE_CALL_SITES[key] : EMPTY;
}

/**
 * True when deleting `key` would break something: it is either a curated
 * system stage or referenced by literal key somewhere in `server/`.
 *
 * This — not `isSystemStage` — is what the DELETE guard consults. The two are
 * separate on purpose: `isSystemStage` drives user-facing badging and stays
 * small; this one drives safety and covers every call site (#3335).
 */
export function isProtectedStage(key) {
  return isSystemStage(key) || CALL_SITE_KEYS.has(key);
}

/** Every key the delete guard protects — the curated set unioned with the derived one. */
export const PROTECTED_STAGE_KEYS = Object.freeze(
  [...new Set([...SYSTEM_STAGE_KEYS, ...CALL_SITE_KEYS])].sort(),
);