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

4.7 KB
Raw Blame
import { EXTENDED_AUDIT_WORKFLOW } from './auditWorkflow.js';
/**
 * The maintenance ladder: the ordered audits PortOS recommends running against a
 * managed app, with a perpetual `claim-issue` drain between every pair so each
 * audit's findings are resolved before the next audit reads the code. Fix mode
 * instead resolves findings in each audit and runs one final drain. Issue-only
 * runs can skip all drains to leave findings open for human review.
 *
 * ONE definition, shared by both runners. `services/maintenanceRun.js` walks
 * these steps directly for the Schedule tab's "Run now" — no quota gates, no
 * burn plan — and the Quota Burn page's "Populate maintenance sequence" saves the
 * same steps into a family plan to be walked later under that family's window
 * gates. The client (`client/src/lib/quotaBurnTasks.js`) imports the order from
 * here so the guidance banner, the prerequisite check and the server's own
 * builder cannot disagree about what the ladder is.
 *
 * Pure: no I/O, no imports out of `lib/`. The step shape is the quota-burn job
 * shape (`quotaBurnTaskRef.js`) so `quotaBurnInvoke.js` can run a step from
 * either runner without knowing which one asked.
 */

import { AUDIT_DEFINITIONS } from './auditCatalog.js';

/** The audits, in the order they should run. */
export const MAINTENANCE_TASK_ORDER = Object.freeze([
  'better-structural-drift', 'simplify', 'module-hygiene', 'better-complexity',
  'performance', 'better-cognitive-load', 'documentation',
]);

export const MAINTENANCE_ORDER_GUIDANCE = 'better-structural-drift → simplify → module-hygiene → better-complexity → performance + better-cognitive-load → documentation';

/** The drain that separates every pair of audits. */
export const MAINTENANCE_DRAIN_TASK = 'claim-issue';

/** The default issue-filing ladder, including interleaved drains. */
export const MAINTENANCE_SEQUENCE_TYPES = Object.freeze(MAINTENANCE_TASK_ORDER.flatMap((type, index) =>
  (index ? [MAINTENANCE_DRAIN_TASK, type] : [type])));

/**
 * The run params an audit step pins. The first six audits explicitly FILE
 * issues (which the drain then claims); documentation explicitly does the work.
 * Fix mode runs audits directly and drains once at the end. Code-producing
 * steps explicitly request PR delivery so issue-only schedule defaults cannot
 * turn their completion into a local-only merge. Review policy still inherits.
 * A drain pins nothing — it inherits the app's saved claim filters.
 */
export const maintenanceStepParams = (taskType, mode = 'file-issues') => (taskType === MAINTENANCE_DRAIN_TASK
  ? {}
  : mode !== 'fix' && taskType !== 'documentation'
    ? { fileIssues: true }
    : { fileIssues: false, useWorktree: true, openPR: true });

/**
 * Build the ladder as run-once steps targeting `appId`, every one pinned to the
 * provider/model/effort the user chose. `effort: null` inherits each scheduled
 * task's saved effort. Ids are `${idPrefix}-${index}`, so a fresh prefix per
 * invocation yields fresh step identities. An optional claimHandler replaces
 * the provider/model/effort bundle for drains only; omitted keeps legacy pins.
 */
export function buildMaintenanceSteps({ appId, idPrefix, providerId = null, model = null, effort = null, mode = 'file-issues', prCompletion = null, claimBetweenAudits = true, claimHandler = null, taskTypes = null, explicitCheck = false, auditDepth = 'quick' }) {
  if (taskTypes !== null && (!Array.isArray(taskTypes) || !taskTypes.length || taskTypes.some(type => !Object.hasOwn(AUDIT_DEFINITIONS, type)))) {
    throw new Error('Quality checks must name known audit categories');
  }
  // An explicit quality selection runs only those audits, without backlog drains.
  const types = taskTypes ? [...new Set(taskTypes)] : mode === 'fix' ? [...MAINTENANCE_TASK_ORDER, MAINTENANCE_DRAIN_TASK] : claimBetweenAudits ? MAINTENANCE_SEQUENCE_TYPES : MAINTENANCE_TASK_ORDER;
  return types.map((taskType, index) => ({
    id: `${idPrefix}-${index}`,
    enabled: true,
    label: '',
    taskRef: { kind: 'builtin', taskType, appId },
    jobType: null,
    runOnce: true,
    drain: taskType === MAINTENANCE_DRAIN_TASK,
    overrides: { ...(taskType === MAINTENANCE_DRAIN_TASK && claimHandler ? claimHandler : { providerId, model, effort }), params: taskTypes ? { ...(auditDepth === 'deep' ? { auditDepth, auditWorkflow: EXTENDED_AUDIT_WORKFLOW } : {}), fileIssues: mode !== 'fix', ...(mode === 'fix' ? { useWorktree: true, openPR: true, ...(prCompletion ? { prCompletion } : {}) } : {}), ...(explicitCheck || auditDepth === 'deep' ? { runInapplicableAudit: true } : {}) } : { ...(auditDepth === 'deep' ? { auditDepth, auditWorkflow: EXTENDED_AUDIT_WORKFLOW } : {}), ...maintenanceStepParams(taskType, mode), ...(prCompletion ? { prCompletion } : {}) } },
  }));
}