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

15.6 KB
Raw Blame
import { basename, join } from 'path';
import { ServerError } from '../lib/errorHandler.js';
import { pathExists, safeJSONParse } from '../lib/fileUtils.js';
import { getOriginInfo, parseGitRemoteUrl, readRemoteUrl } from '../lib/gitRemote.js';
import { githubApiHost, hostToWorkTracker, isGithubHost } from '../lib/workTracker.js';
import { execGitSafe, fetchOrigin, isFetchFresh, resolveForgeForRepo } from './git.js';
import { execGh } from './github.js';
import { forgeMissingScopesOf } from '../lib/forgeAccessErrors.js';
import { forgeScopeMissingError } from './forgeScopeRefresh.js';
import { inspectPinnedSubmoduleDrift } from './gitPinnedSubmodules.js';

const GH_TIMEOUT_MS = 60_000;

const comparisonState = (ahead, behind) => {
  if (ahead > 0 && behind > 0) return 'diverged';
  if (behind > 0) return 'behind';
  if (ahead > 0) return 'ahead';
  return 'current';
};

function parseRevisionCounts(result) {
  if (result?.exitCode !== 0) return null;
  const [aheadText, behindText] = result.stdout.trim().split(/\s+/);
  const ahead = Number.parseInt(aheadText, 10);
  const behind = Number.parseInt(behindText, 10);
  if (!Number.isInteger(ahead) || !Number.isInteger(behind)) return null;
  return { ahead, behind, state: comparisonState(ahead, behind) };
}

const repositoryIdentity = (fullName, host = 'github.com') => {
  if (typeof fullName !== 'string' || !fullName.trim()) return null;
  const parts = fullName.trim().split('/');
  if (parts.length !== 2 || parts.some((part) => !part)) return null;
  return {
    host: githubApiHost(host),
    owner: parts[0],
    repo: parts[1],
    fullName: `${parts[0]}/${parts[1]}`,
  };
};

function remoteIdentity(url) {
  const parsed = parseGitRemoteUrl(url);
  if (!parsed) return null;
  return {
    host: githubApiHost(parsed.host),
    owner: parsed.owner,
    repo: parsed.repo,
    fullName: `${parsed.owner}/${parsed.repo}`,
  };
}

async function githubRepositoryMetadata(repoPath, origin) {
  if (!origin?.fullName || !isGithubHost(origin.host)) return null;
  const forge = await resolveForgeForRepo(repoPath);
  const host = githubApiHost(origin.host);
  const raw = await execGh([
    'api', ...(host === 'github.com' ? [] : ['--hostname', host]),
    `repos/${origin.fullName}`, '--jq',
    '{fullName: .full_name, defaultBranch: .default_branch, isFork: .fork, '
      + 'canPush: .permissions.push, '
      + 'parentFullName: .parent.full_name, parentDefaultBranch: .parent.default_branch, '
      + 'sourceFullName: .source.full_name, sourceDefaultBranch: .source.default_branch}',
  ], GH_TIMEOUT_MS, {
    cwd: repoPath,
    env: forge?.env || process.env,
  }).catch(() => null);
  const parsed = safeJSONParse(raw, null);
  return parsed && typeof parsed.fullName === 'string' ? parsed : null;
}

/**
 * Resolve one checkout's origin → canonical-upstream topology. GitHub's own
 * fork metadata is authoritative, so renamed forks work too. An explicit
 * `upstream` remote is the offline/cross-forge fallback; otherwise a repository
 * that GitHub confirms is not a fork is its own canonical source.
 */
export async function resolveRepositoryTopology(repoPath) {
  const origin = await getOriginInfo(repoPath);
  if (!origin.hasOrigin) {
    return {
      origin: { ...origin, canPush: null },
      upstream: null,
      isFork: false,
      available: false,
      error: 'No origin remote configured',
    };
  }

  const [metadata, upstreamUrl] = await Promise.all([
    githubRepositoryMetadata(repoPath, origin),
    readRemoteUrl('upstream', repoPath).catch(() => null),
  ]);

  const apiUpstream = repositoryIdentity(
    metadata?.sourceFullName || metadata?.parentFullName,
    origin.host,
  );
  const explicitUpstream = remoteIdentity(upstreamUrl);
  const upstream = metadata
    ? apiUpstream || repositoryIdentity(origin.fullName, origin.host)
    : explicitUpstream;
  const isFork = Boolean(upstream && origin.fullName
    && upstream.fullName.toLowerCase() !== origin.fullName.toLowerCase());
  const defaultBranch = apiUpstream
    ? (metadata.sourceDefaultBranch || metadata.parentDefaultBranch || metadata.defaultBranch || 'main')
    : metadata?.defaultBranch || null;

  // `canPush` is tri-state on purpose: `false` only when the forge answered and
  // said no, `null` when nothing answered. A fork PortOS cannot push to cannot
  // be fast-forwarded, and an unknown answer must not silently retract a sync
  // PortOS has always offered.
  return {
    origin: {
      ...origin,
      isFork,
      isUpstream: upstream ? !isFork : null,
      canPush: typeof metadata?.canPush === 'boolean' ? metadata.canPush : null,
    },
    upstream: upstream ? { ...upstream, branch: defaultBranch } : null,
    isFork,
    available: Boolean(upstream),
    error: upstream ? null : 'Could not determine the canonical upstream repository',
  };
}

async function compareForkWithUpstream(checkout, repoPath) {
  if (!checkout?.origin?.isFork || !checkout.origin.fullName || !checkout.upstream?.fullName) return null;
  if (!isGithubHost(checkout.origin.host) || checkout.origin.host !== checkout.upstream.host) return null;
  const branch = checkout.upstream.branch || checkout.branch || 'main';
  const upstreamOwner = checkout.upstream.owner;
  const originOwner = checkout.origin.owner;
  const basehead = encodeURIComponent(`${upstreamOwner}:${branch}...${originOwner}:${branch}`);
  const forge = await resolveForgeForRepo(repoPath);
  const host = githubApiHost(checkout.origin.host);
  const raw = await execGh([
    'api', ...(host === 'github.com' ? [] : ['--hostname', host]),
    `repos/${checkout.upstream.fullName}/compare/${basehead}`, '--jq',
    '{status: .status, ahead: .ahead_by, behind: .behind_by}',
  ], GH_TIMEOUT_MS, {
    cwd: repoPath,
    env: { ...(forge?.env || process.env), GH_HOST: host },
  }).catch(() => null);
  const parsed = safeJSONParse(raw, null);
  if (!parsed || !Number.isInteger(parsed.ahead) || !Number.isInteger(parsed.behind)) {
    return { available: false, ahead: null, behind: null, state: 'unknown', error: 'Could not compare the fork with canonical upstream' };
  }
  return {
    available: true,
    ahead: parsed.ahead,
    behind: parsed.behind,
    state: comparisonState(parsed.ahead, parsed.behind),
    error: null,
  };
}

async function inspectCheckout({ id, label, repoPath }) {
  const present = typeof repoPath === 'string' && repoPath.trim().length > 0
    && await pathExists(join(repoPath, '.git'));
  if (!present) {
    return {
      id, label, present: false, branch: null, head: null, shortHead: null, clean: null,
      origin: null, upstream: null, localVsOrigin: null, forkVsUpstream: null,
      remoteFresh: false, remoteError: 'Checkout not found',
    };
  }

  const [branchResult, headResult, worktreeResult, topology] = await Promise.all([
    execGitSafe(['rev-parse', '--abbrev-ref', 'HEAD'], repoPath, { ignoreExitCode: true }),
    execGitSafe(['rev-parse', 'HEAD'], repoPath, { ignoreExitCode: true }),
    execGitSafe(['status', '--porcelain'], repoPath, { ignoreExitCode: true }),
    resolveRepositoryTopology(repoPath),
  ]);
  const branchName = branchResult.exitCode === 0 ? branchResult.stdout.trim() : null;
  const branch = branchName && branchName !== 'HEAD' ? branchName : null;
  const head = headResult.exitCode === 0 ? headResult.stdout.trim() : null;
  const clean = worktreeResult.exitCode === 0 ? worktreeResult.stdout.trim().length === 0 : null;
  const submodulesOnly = clean === false
    && (await inspectPinnedSubmoduleDrift(repoPath)).onlyRepairable;
  // Skip the network hop when this checkout's remote refs were already
  // refreshed inside the freshness window — the refs really are current, so
  // `fresh: true` stays truthful. This read used to be reachable only from the
  // app's Git tab; the Eidoverse page now runs it on every visit, where an
  // ungated fetch would cost two `git fetch`es per mount (twice that under
  // React StrictMode) for an answer that cannot have changed.
  const fetchResult = !topology.origin.hasOrigin
    ? { fresh: false, error: topology.error }
    : isFetchFresh(repoPath)
      ? { fresh: true, error: topology.error }
      : await fetchOrigin(repoPath).then(
        () => ({ fresh: true, error: topology.error }),
        () => ({ fresh: false, error: 'Could not refresh the origin repository' }),
      );

  const originRef = branch ? `refs/remotes/origin/${branch}` : null;
  const [originHeadResult, countsResult] = originRef
    ? await Promise.all([
      execGitSafe(['rev-parse', '--verify', originRef], repoPath, { ignoreExitCode: true }),
      execGitSafe(['rev-list', '--left-right', '--count', `HEAD...${originRef}`], repoPath, { ignoreExitCode: true }),
    ])
    : [null, null];
  const originHead = originHeadResult?.exitCode === 0 ? originHeadResult.stdout.trim() : null;
  const checkout = {
    id,
    label,
    present: true,
    branch,
    head,
    shortHead: head?.slice(0, 7) || null,
    clean,
    submodulesOnly,
    origin: {
      ...topology.origin,
      url: topology.origin.originUrl,
      head: originHead,
      shortHead: originHead?.slice(0, 7) || null,
    },
    upstream: topology.upstream
      ? {
        fullName: topology.upstream.fullName,
        owner: topology.upstream.owner,
        branch: topology.upstream.branch,
        host: topology.upstream.host,
      }
      : null,
    localVsOrigin: countsResult ? parseRevisionCounts(countsResult) : null,
    remoteFresh: fetchResult.fresh,
    remoteError: fetchResult.error,
  };
  return { ...checkout, forkVsUpstream: await compareForkWithUpstream(checkout, repoPath) };
}

/**
 * Can a managed update fast-forward THIS checkout's origin fork from canonical
 * upstream? Only when all three hold:
 *
 * - it is the primary checkout — `syncManagedAppFork` only ever touches
 *   `app.repoPath`, so a companion's fork has no sync path at all;
 * - the credential can push to that fork — cloning someone else's fork of a
 *   third project is normal (Eidoverse's video checkout is `anima-research`'s
 *   fork), and PortOS can never move a repository it can only read;
 * - the fork has not diverged — a diverged fork cannot be fast-forwarded.
 *
 * This is what separates "behind, and one click fixes it" from "behind, and
 * nothing PortOS can do will change that" — an out-of-date advisory raised for
 * the latter is unactionable and never clears (#6321).
 */
const isForkSyncable = (source) => source.id === 'primary'
  && Boolean(source.origin?.isFork)
  && source.origin?.canPush !== false
  && source.forkVsUpstream?.state !== 'diverged';

function sourceDescriptors(app) {
  const companions = Array.isArray(app?.companionRepoPaths)
    ? [...new Set(app.companionRepoPaths)].filter((path) => path && path !== app.repoPath)
    : [];
  return [
    { id: 'primary', label: app.name || 'Application', repoPath: app.repoPath },
    ...companions.map((repoPath, index) => ({
      id: `companion-${index + 1}`,
      label: basename(repoPath) || `Companion repository ${index + 1}`,
      repoPath,
    })),
  ];
}

function publicTarget(repository, role) {
  if (!repository?.fullName) return null;
  const host = repository.host || 'github.com';
  const forge = hostToWorkTracker(host);
  return {
    role,
    forge,
    fullName: repository.fullName,
    repoSpec: isGithubHost(host) ? `${githubApiHost(host)}/${repository.fullName}` : null,
  };
}

export async function getManagedAppRepositorySources(app) {
  const descriptors = sourceDescriptors(app);
  const inspected = await Promise.all(descriptors.map(inspectCheckout));
  const sources = inspected.map((source) => ({ ...source, forkSyncable: isForkSyncable(source) }));
  const primary = sources[0] || null;
  const originTarget = publicTarget(primary?.origin, 'origin');
  const upstreamTarget = publicTarget(primary?.upstream, 'upstream');
  const canChoose = Boolean(primary?.origin?.isFork && originTarget && upstreamTarget);
  return {
    kind: 'managed-app',
    checkedAt: new Date().toISOString(),
    // Only what a managed update can actually pull forward: any checkout behind
    // its own origin, plus a fork behind upstream that PortOS is allowed to
    // fast-forward. A fork PortOS can only read stays visible on the Git tab
    // but never claims an update is available.
    updateAvailable: sources.some((source) => source.submodulesOnly || source.localVsOrigin?.behind > 0
      || (source.forkSyncable && (source.forkVsUpstream?.behind || 0) > 0)),
    updatePullsAll: true,
    updateRestartsApp: Array.isArray(app?.pm2ProcessNames) && app.pm2ProcessNames.length > 0,
    issueTargets: {
      default: canChoose || primary?.origin?.isUpstream == null ? 'upstream' : 'origin',
      canChoose,
      origin: originTarget,
      upstream: upstreamTarget,
    },
    sources,
  };
}

export async function resolveManagedAppIssueTarget(app, preference = 'upstream') {
  const topology = await resolveRepositoryTopology(app.repoPath);
  const origin = publicTarget(topology.origin, 'origin');
  if (preference === 'origin') return origin;
  if (!topology.available) return null;
  const upstream = publicTarget(topology.upstream, 'upstream');
  if (!topology.isFork || !upstream) return origin;
  return upstream;
}

/** Fast-forward the primary checkout's GitHub fork without touching local files. */
export async function syncManagedAppFork(app) {
  const topology = await resolveRepositoryTopology(app.repoPath);
  const { origin, upstream } = topology;
  if (!origin?.hasOrigin) {
    throw new ServerError('The app checkout has no Git origin.', { status: 400, code: 'NO_ORIGIN' });
  }
  if (!isGithubHost(origin.host)) {
    throw new ServerError('Fork sync is available only for GitHub origins.', { status: 400, code: 'NOT_GITHUB' });
  }
  if (!topology.available) {
    throw new ServerError('Could not determine the canonical upstream repository.', { status: 502, code: 'UPSTREAM_UNAVAILABLE' });
  }
  if (!topology.isFork) {
    throw new ServerError(`The origin is already the canonical ${origin.fullName} repository.`, { status: 400, code: 'ALREADY_UPSTREAM' });
  }
  if (origin.canPush === false) {
    throw new ServerError(
      `The ${origin.fullName} fork belongs to someone else — PortOS can read it but cannot push to it, `
      + `so it cannot be fast-forwarded from ${upstream.fullName}. Ask its owner to sync it, or point this app at a fork you control.`,
      { status: 403, code: 'FORK_NOT_WRITABLE' },
    );
  }
  const branch = upstream.branch || null;
  const forge = await resolveForgeForRepo(app.repoPath);
  const args = ['repo', 'sync', origin.fullName, '--source', upstream.fullName];
  if (branch) args.push('--branch', branch);
  const output = await execGh(args, GH_TIMEOUT_MS, {
    cwd: app.repoPath,
    env: { ...(forge?.env || process.env), GH_HOST: githubApiHost(origin.host) },
  }).catch((error) => {
    // Syncing upstream commits that touch `.github/workflows/` needs the token's
    // `workflow` scope: a credential fix, not a failed sync.
    const missingScopes = forgeMissingScopesOf(error);
    if (missingScopes.length > 0) {
      throw forgeScopeMissingError({ host: githubApiHost(origin.host), scopes: missingScopes, error: error.message });
    }
    if (/fast forward|diverge|non-fast/i.test(error.message || '')) {
      throw new ServerError(
        `The ${origin.fullName} fork has commits that cannot be fast-forwarded from ${upstream.fullName}. Reconcile those commits on GitHub before syncing.`,
        { status: 409, code: 'FORK_DIVERGED' },
      );
    }
    throw new ServerError(`Could not sync the app fork: ${error.message}`, { status: 502, code: 'FORK_SYNC_FAILED' });
  });
  return {
    synced: true,
    alreadyUpToDate: /up to date/i.test(output),
    fullName: origin.fullName,
    source: upstream.fullName,
    branch,
    message: output.trim(),
  };
}