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

16.1 KB
Raw Blame
/**
 * "Is this checkout in a state an unattended update may run against?"
 *
 * An update — either channel — moves the checkout: `update.sh` switches to the
 * default branch and stashes whatever was in the way, and the App Management
 * path runs `updateDefaultBranch`, which checks out, fast-forwards, and falls
 * back to `pull --rebase --autostash`. Both are fine when a human is watching
 * and can read the stash instructions. Unattended, they are not: a stash nobody
 * is told about reads as lost work, and a rebase conflict leaves the install
 * half-updated with nothing to notice it.
 *
 * So the auto-updater refuses to start until the checkout is ON the default
 * branch and CLEAN, and this module is what decides that — plus what can be put
 * right mechanically. These remedies are safe enough to run unattended, because
 * each preserves local work:
 *
 *   - checking out the default branch from a CLEAN feature branch (the commits
 *     stay on the branch ref; nothing is discarded), and
 *   - restoring modified auto-generated lockfiles (`npm install` rewrites them
 *     as a side effect, and the update reinstalls anyway), and
 *   - checking out pinned submodule commits when their current checkouts are
 *     clean ancestors of those pins (including recursively stale children).
 *
 * Everything else — uncommitted work, an unpushed commit, an interrupted
 * rebase/merge, conflict markers — is judgement no script should make on a
 * user's repository. That queues a CoS task instead, which is the same
 * escalation `appUpdater.failWithGitConflict` already uses for a conflicted
 * managed-app pull.
 */

import { isAbsolute } from 'path';
import { PATHS } from '../lib/fileUtils.js';
import { execGitSafe } from '../lib/execGit.js';
import * as gitService from './git.js';
import { countAheadBehind, detectOperationInProgress } from './repoSync.js';
import { classifyWorktreeDirt } from './worktreeManager.js';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';

/** First line of the repair task — stable so `addTask`'s dedup collapses reruns. */
export const REPO_REPAIR_TASK_DESCRIPTION = 'Restore the PortOS checkout to a clean default branch so automatic updates can run';

/** Why a checkout is not ready, ordered most-blocking first for the UI. */
const REASON_LABELS = {
  'git-unreadable': 'the checkout could not be inspected',
  'no-default-branch': 'the origin default branch could not be resolved',
  'merge-in-progress': 'a merge or rebase is in progress',
  'operation-check-unreadable': 'whether a merge or rebase is in progress could not be established',
  'conflicted-files': 'the working tree has unresolved conflicts',
  'uncommitted-changes': 'the working tree has uncommitted changes',
  'unpushed-commits': 'the default branch has local commits that are not on origin',
  'divergence-unreadable': 'how far the checkout has diverged from origin could not be read',
  'agent-at-work': 'a CoS agent is working in this checkout',
  'agent-check-unreadable': 'whether a CoS agent is working in this checkout could not be established',
  'detached-head': 'HEAD is detached',
  'wrong-branch': 'the checkout is not on the default branch',
};

/** What each mechanical remedy will do, for a verdict that has no blocking reason. */
const REPAIRABLE_LABELS = {
  'restore-lockfiles': 'auto-generated lockfiles need restoring',
  'checkout-default': 'the checkout needs switching back to the default branch',
  'update-submodules': 'submodule checkouts need updating to their pinned commits',
};

const describe = (code) => REASON_LABELS[code] || REPAIRABLE_LABELS[code] || code;

/** Absolute paths only — a relative path would resolve against the server's cwd. */
const resolveRepoPath = (repoPath) => (isAbsolute(repoPath || '') ? repoPath : PATHS.root);

/**
 * How far HEAD and its origin counterpart have diverged, via `repoSync`'s
 * counter so the left/right → ahead/behind mapping is decided in one place.
 *
 * `null` means the read FAILED — deliberately not 0. Every missing fact here
 * would otherwise default to the value that looks safe, and "0 commits ahead"
 * is precisely the value that unlocks the update. The caller refuses on a null.
 */
async function divergence(repoPath, branch) {
  const counts = await countAheadBehind(repoPath, 'HEAD', `refs/remotes/origin/${branch}`);
  return counts || { ahead: null, behind: null };
}

/**
 * Inspect the checkout without touching it.
 *
 * @param {object} [options]
 * @param {string} [options.repoPath] - defaults to this install's root.
 * @param {boolean} [options.fetch] - refresh origin refs first, so `behind`
 *   answers "is there anything to update to?" rather than "was there, last
 *   time something fetched?". The auto-updater wants this; a status read for
 *   the UI does not.
 * @returns {Promise<object>} the readiness verdict.
 */
export async function checkUpdateRepoReadiness({ repoPath, fetch = false } = {}) {
  const dir = resolveRepoPath(repoPath);
  // ONE verdict shape on every path, including the failure ones — the scheduler
  // and the UI both read `summary` and `repairable`, and an early return that
  // omitted them forced a fallback message that named the wrong cause.
  const verdict = (fields) => {
    const reasons = fields.reasons || [];
    const repairable = fields.repairable || [];
    return {
      repoPath: dir,
      branch: null, defaultBranch: null, interrupted: null, ahead: null, behind: null,
      lockfilePaths: [], submodulePaths: [],
      ...fields,
      reasons,
      repairable,
      // Ready means: nothing to refuse AND nothing left to repair. A repairable
      // checkout becomes ready only after `prepareUpdateRepo` actually repairs it.
      ready: reasons.length === 0 && repairable.length === 0,
      // A checkout that is merely repairable must NOT wake an agent — that is
      // the whole point of the repairable/blocking split. Nor may an unreadable
      // one: there is nothing for an agent to resolve if git itself is the
      // problem.
      needsAgent: reasons.length > 0 && !reasons.includes('git-unreadable'),
      // A repairable-only verdict is still `ready: false`, and the panel renders
      // `summary` for anything not ready — leaving it null there made the UI fall
      // back to a generic "wrong branch" line that named the wrong cause.
      summary: reasons.length
        ? reasons.map(describe).join('; ')
        : repairable.length ? repairable.map(describe).join('; ') : null,
    };
  };

  if (!(await gitService.isRepo(dir).catch(() => false))) {
    return verdict({ reasons: ['git-unreadable'] });
  }
  if (fetch) await gitService.fetchOrigin(dir).catch(() => undefined);

  // Five independent reads — nothing below depends on another's answer, and
  // serializing them cost ~110ms of git spawns on a path the Update tab polls.
  // `allowRemote` follows `fetch`: without it `getDefaultBranch` may run
  // `git remote set-head --auto`, a 5s network call, on that same poll.
  const [defaultBranch, branch, porcelain, interrupted, activeAgentId] = await Promise.all([
    gitService.getDefaultBranch(dir, { strict: true, allowRemote: fetch }).catch(() => null),
    gitService.getBranch(dir).catch(() => null),
    gitService.getStatusPorcelain(dir).catch(() => null),
    // `'unknown'` = the marker read itself failed, which is not "no operation".
    detectOperationInProgress(dir).catch(() => 'unknown'),
    // A CoS agent working in THIS checkout (a `useWorktree: false` task,
    // including the repair task this module queues) owns the branch it is on.
    // Moving it, or running update.sh's pm2 restart under it, is the branch-jack
    // `repoSync` refuses on for the same reason — and the idle gate alone would
    // not catch a paused agent that still holds the tree.
    gitService.findActiveAgentInWorkspace(dir, { includePaused: true, failClosed: true }).catch(() => 'unknown'),
  ]);
  if (branch === null || porcelain === null) {
    return verdict({ defaultBranch, reasons: ['git-unreadable'] });
  }

  const { repairablePaths: submodulePaths } = porcelain.trim()
    ? await inspectPinnedSubmoduleDrift(dir)
    : { repairablePaths: [] };
  const dirt = classifyWorktreeDirt(porcelain, { ignoredPaths: submodulePaths });
  const conflicted = porcelain.split('\n').some((line) => /^(DD|AU|UD|UA|DU|AA|UU) /.test(line));
  const detached = branch === 'HEAD';
  const onDefaultBranch = Boolean(defaultBranch) && branch === defaultBranch;
  const { ahead, behind } = defaultBranch ? await divergence(dir, defaultBranch) : { ahead: null, behind: null };

  const reasons = [];
  const repairable = [];
  // Distinct codes: "an agent holds this checkout" is a wait; "the registry
  // could not be read" is a fault the user has to see named, not a phantom agent.
  if (activeAgentId === 'unknown') reasons.push('agent-check-unreadable');
  else if (activeAgentId) reasons.push('agent-at-work');
  if (!defaultBranch) reasons.push('no-default-branch');
  // Same split as the agent check: a failed marker read must not be reported as
  // an interrupted rebase the user would go looking for and not find.
  if (interrupted === 'unknown') reasons.push('operation-check-unreadable');
  else if (interrupted) reasons.push('merge-in-progress');
  if (conflicted) reasons.push('conflicted-files');
  if (dirt.hasRealChanges) reasons.push('uncommitted-changes');
  else if (!dirt.clean) repairable.push('restore-lockfiles');
  if (submodulePaths.length) repairable.push('update-submodules');
  if (detached) reasons.push('detached-head');
  else if (defaultBranch && !onDefaultBranch) {
    // A clean feature branch is a mechanical checkout away from ready; a dirty
    // one is already refused above, so the branch move is never what loses work.
    if (dirt.hasRealChanges || conflicted || interrupted) reasons.push('wrong-branch');
    else repairable.push('checkout-default');
  }
  // Only meaningful ON the default branch: a feature branch is expected to be
  // ahead, and the checkout-default remedy leaves those commits where they are.
  // An UNREADABLE count refuses too — `null > 0` is false, so treating it as a
  // number here would make "could not tell" indistinguishable from "nothing
  // unpushed", in the one path whose whole premise is never losing work.
  if (onDefaultBranch && (ahead === null || ahead > 0)) {
    reasons.push(ahead === null ? 'divergence-unreadable' : 'unpushed-commits');
  }

  // The paths of the user's own uncommitted work are deliberately NOT returned:
  // this verdict is served to the browser on the Update tab's poll, and the
  // reason codes already say what is wrong. `lockfilePaths` is the exception —
  // `prepareUpdateRepo` restores exactly those paths and nothing else.
  return verdict({
    branch,
    defaultBranch,
    interrupted,
    ahead,
    behind,
    lockfilePaths: dirt.lockfilePaths,
    submodulePaths,
    reasons,
    repairable,
  });
}

/**
 * Apply the mechanical remedies, then re-inspect.
 *
 * Never destroys work: the only discard is a modified auto-generated lockfile,
 * and the only branch move happens from a clean tree.
 *
 * @returns {Promise<{verdict: object, actions: string[]}>} the POST-repair
 *   verdict, plus what was actually done (for the log line and the runtime record).
 */
export async function prepareUpdateRepo({ repoPath = PATHS.root } = {}) {
  const dir = resolveRepoPath(repoPath);
  // No fetch: the one caller reads with `fetch: true` before its idle gate and
  // then calls this, so a second network hop would only re-answer that read.
  const before = await checkUpdateRepoReadiness({ repoPath: dir, fetch: false });
  if (before.ready || before.reasons.length || before.repairable.length === 0) return { verdict: before, actions: [] };

  const actions = [];
  if (before.repairable.includes('update-submodules')) {
    const sync = await execGitSafe(['submodule', 'sync', '--recursive'], dir);
    const update = sync.exitCode === 0 && await execGitSafe([
      'submodule', 'update', '--init', '--recursive', '--checkout', '--', ...before.submodulePaths,
    ], dir, { timeout: 120000 });
    if (update.exitCode === 0) actions.push('updated submodules to their pinned commits');
  }
  if (before.repairable.includes('restore-lockfiles') && before.lockfilePaths.length) {
    // By explicit path, never `-- .`: the classifier proved these specific
    // paths are auto-generated lockfiles, and a pathspec of `.` would discard
    // anything the classifier had not looked at (a file that appeared between
    // the two calls, say) along with them.
    const restore = await execGitSafe(['checkout', '--', ...before.lockfilePaths], dir, { ignoreExitCode: true });
    if (restore.exitCode === 0) actions.push(`restored ${before.lockfilePaths.length} auto-generated lockfile(s)`);
  }
  if (before.repairable.includes('checkout-default') && before.defaultBranch) {
    const checkout = await execGitSafe(['checkout', before.defaultBranch], dir, { ignoreExitCode: true });
    if (checkout.exitCode === 0) actions.push(`switched to ${before.defaultBranch}`);
  }

  // Re-inspect rather than assuming the remedies worked: a checkout can still
  // fail (a permission problem, a hook), and a verdict that claimed otherwise
  // would hand the updater a checkout it never verified.
  const verdict = await checkUpdateRepoReadiness({ repoPath: dir, fetch: false });
  if (actions.length) console.log(`🧹 Auto-update repo prep: ${actions.join(', ')}`);
  return { verdict, actions };
}

/**
 * Queue a CoS agent to resolve what no script should: uncommitted work, an
 * unpushed commit, an interrupted rebase, conflict markers.
 *
 * The first line is constant, so `addTask`'s description+app dedup collapses
 * every subsequent tick onto the one open task ONLY WHILE THAT TASK STAYS
 * OPEN — once the agent finishes (fixed or not) the task flips to `completed`
 * and the dedup no longer matches. What actually bounds re-dispatch after that
 * is the caller: `autoUpdateScheduler.repairDispatchDue` gates a call to this
 * function on a `repairQueuedAt` timestamp stamped right after a successful
 * enqueue, so a stand-down agent costs one dispatch per cooldown window
 * rather than one per poll (#7468). That gate is deliberately separate from
 * the update cooldown, so a checkout this agent fixes still updates on the
 * very next idle tick. The task store is imported lazily — this module is on
 * the update path, the repair branch is rare, and a static import would pull
 * the whole CoS state graph into that closure.
 *
 * Never rejects: a failed enqueue must not mask the readiness refusal itself.
 *
 * @returns {Promise<{id: string, duplicate?: boolean}|null>}
 */
export async function queueRepoRepairTask(verdict) {
  const context = [
    'Automatic PortOS updates are configured, but they are held back because this checkout is not in a state an unattended update may run against.',
    '',
    `Repository: ${verdict.repoPath}`,
    `Current branch: ${verdict.branch || 'unknown'}`,
    `Default branch: ${verdict.defaultBranch || 'unknown'}`,
    verdict.interrupted ? `Interrupted operation: ${verdict.interrupted}` : null,
    Number.isFinite(verdict.ahead) ? `Local commits not on origin: ${verdict.ahead}` : null,
    '',
    'What is blocking the update:',
    ...verdict.reasons.map((code, index) => `${index + 1}. ${describe(code)}`),
    '',
    `Resolve it so the checkout ends up clean on ${verdict.defaultBranch || 'the default branch'}: finish or abort any in-progress `
      + 'rebase/merge, land or park uncommitted work (commit and open a PR, or restore it — never discard it silently), '
      + 'and push or PR any local commits that are not on origin. Do not run the update itself; PortOS resumes automatically '
      + 'once the checkout is clean.',
    '',
    'Work in the primary checkout, not a worktree — the state that needs fixing is there.',
  ].filter((line) => line !== null).join('\n');

  return import('./cosTaskStore.js')
    .then(({ addTask }) => addTask({
      description: REPO_REPAIR_TASK_DESCRIPTION,
      priority: 'HIGH',
      app: PORTOS_APP_ID,
      context,
      useWorktree: false,
    }, 'internal'))
    .catch((err) => {
      console.error(`❌ Failed to queue auto-update repo repair task: ${err.message}`);
      return null;
    });
}