@naswerks/periscope 1.0.0 → 1.0.1

package/src/bin/posture.ts

@@ -0,0 +1,232 @@
+/**
+ * What this host is, said once: its ids, its credential, its workspace, its link and where each
+ * setting came from. `serve` prints the one-line form at start-up and `status` prints the whole,
+ * from one description, so the two can never disagree about the host they describe. Pure over its
+ * inputs; the reads that fill them live with the verbs.
+ */
+import { CONFIG_KEYS, WIRE_CONFIGURABLE_KEYS, configFilePath } from '../host/config-file.js';
+import type { LinkStateRecord } from '../host/link-state-file.js';
+import type { CredentialPosture } from './serve.js';
+import { workspaceCapabilitiesOf } from './workspaces.js';
+
+export interface PostureInputs {
+  /** The process environment as it was. */
+  readonly raw: NodeJS.ProcessEnv;
+  /** The environment with the config file filling its absences. */
+  readonly merged: NodeJS.ProcessEnv;
+  /** The values the config file holds, so a key can say which source it came from. */
+  readonly fileValues: Readonly<Record<string, string>>;
+  /** What `readCredential` decided, or its refusal. */
+  readonly credential: CredentialPosture | string;
+  /** The cached token's expiry in epoch milliseconds, when a token cache is readable. */
+  readonly tokenExpiresAtMs: number | null;
+  readonly nowMs: number;
+  readonly link: LinkStateRecord | null;
+  /** Whether the process that wrote the link record is still alive. */
+  readonly pidAlive: (pid: number) => boolean;
+  /** The machine's hostname, the host id's fallback. */
+  readonly hostname: string;
+}
+
+export type CredentialKind = 'paired' | 'token' | 'absent' | 'unreadable';
+export type WorkspaceMode = 'git-worktree' | 'plain' | 'none';
+export type Source = 'environment' | 'config-file' | 'default' | 'unset';
+
+export interface Setting {
+  readonly key: string;
+  readonly value: string | null;
+  readonly source: Source;
+  /** Set in both places, and the environment won. */
+  readonly shadowsFile: boolean;
+}
+
+export interface Posture {
+  readonly hostId: {
+    readonly configured: string;
+    readonly paired: string | null;
+    readonly effective: string;
+  };
+  readonly credential: {
+    readonly kind: CredentialKind;
+    readonly expiresAt: string | null;
+    readonly expired: boolean;
+    readonly problem: string | null;
+  };
+  readonly workspace: { readonly mode: WorkspaceMode; readonly branchScheme: string | null };
+  readonly sources: readonly Setting[];
+  readonly configFile: string | null;
+  readonly link: {
+    readonly state: string;
+    readonly cause: string | null;
+    readonly at: string | null;
+    readonly detail: string | null;
+    readonly negotiatedVersion: number | null;
+    readonly pid: number | null;
+    readonly alive: boolean;
+  };
+}
+
+function settingOf(key: string, inputs: PostureInputs): Setting {
+  const fromEnv = inputs.raw[key];
+  const fromFile = inputs.fileValues[key];
+  const inEnv = fromEnv !== undefined && fromEnv !== '';
+  const inFile = fromFile !== undefined && fromFile !== '';
+  if (inEnv) return { key, value: fromEnv, source: 'environment', shadowsFile: inFile };
+  if (inFile) return { key, value: fromFile, source: 'config-file', shadowsFile: false };
+  const merged = inputs.merged[key];
+  if (merged !== undefined && merged !== '')
+    return { key, value: merged, source: 'default', shadowsFile: false };
+  return { key, value: null, source: 'unset', shadowsFile: false };
+}
+
+export function describePosture(inputs: PostureInputs): Posture {
+  const keys = [
+    ...new Set<string>([
+      ...CONFIG_KEYS,
+      ...WIRE_CONFIGURABLE_KEYS,
+      'PERISCOPE_HOST_ID',
+      'PERISCOPE_CONFIG_DIR',
+    ]),
+  ];
+  const sources = keys.map((key) => settingOf(key, inputs));
+  const value = (key: string): string | null => sources.find((one) => one.key === key)?.value ?? null;
+
+  const configured = value('PERISCOPE_HOST_ID') ?? inputs.hostname;
+  const paired = typeof inputs.credential === 'string' ? null : inputs.credential.pairedHostId;
+
+  let kind: CredentialKind;
+  let problem: string | null = null;
+  if (typeof inputs.credential === 'string') {
+    kind = 'unreadable';
+    problem = inputs.credential;
+  } else if (inputs.credential.pairedHostId !== null) kind = 'paired';
+  else if (inputs.credential.credential !== null) kind = 'token';
+  else kind = 'absent';
+  const expiresAt =
+    kind === 'token' && inputs.tokenExpiresAtMs !== null
+      ? new Date(inputs.tokenExpiresAtMs).toISOString()
+      : null;
+  const expired =
+    kind === 'token' && inputs.tokenExpiresAtMs !== null && inputs.tokenExpiresAtMs <= inputs.nowMs;
+
+  const capabilities = workspaceCapabilitiesOf({
+    workspaceRoot: value('PERISCOPE_WORKSPACE_ROOT'),
+    repositoryRoot: value('PERISCOPE_REPOSITORY_ROOT'),
+    branchScheme: value('PERISCOPE_BRANCH_SCHEME'),
+  });
+  const mode: WorkspaceMode = capabilities.includes('workspace:git-worktree')
+    ? 'git-worktree'
+    : capabilities.includes('workspace:plain')
+      ? 'plain'
+      : 'none';
+
+  const link = inputs.link;
+  return {
+    hostId: { configured, paired, effective: paired ?? configured },
+    credential: { kind, expiresAt, expired, problem },
+    workspace: { mode, branchScheme: value('PERISCOPE_BRANCH_SCHEME') },
+    sources,
+    configFile: configFilePath(inputs.raw),
+    link:
+      link === null
+        ? {
+            state: 'unknown',
+            cause: null,
+            at: null,
+            detail: null,
+            negotiatedVersion: null,
+            pid: null,
+            alive: false,
+          }
+        : {
+            state: link.state,
+            cause: link.cause,
+            at: link.at,
+            detail: link.detail,
+            negotiatedVersion: link.negotiatedVersion,
+            pid: link.pid,
+            alive: inputs.pidAlive(link.pid),
+          },
+  };
+}
+
+/** The one line `serve` prints at start-up: the host, the credential, the workspace, the config file. */
+export function postureLine(posture: Posture): string {
+  // A token posture names the cache it will present: configured for a token with none cached is
+  // the state every refusal at the first dial comes from, and it is visible here first.
+  const credential =
+    posture.credential.kind === 'token'
+      ? posture.credential.expiresAt !== null
+        ? `token (expires ${posture.credential.expiresAt})`
+        : 'token (no cache yet - sign in first)'
+      : posture.credential.kind;
+  return (
+    `host ${posture.hostId.effective}` +
+    (posture.hostId.paired !== null && posture.hostId.paired !== posture.hostId.configured
+      ? ` (paired; configured ${posture.hostId.configured})`
+      : '') +
+    ` · credential ${credential} · workspace ${posture.workspace.mode}` +
+    ` · config file ${posture.configFile ?? '(none)'}`
+  );
+}
+
+/** The whole posture, one fact per line, for `periscope status`. */
+export function renderPosture(posture: Posture): string[] {
+  const lines: string[] = [];
+  const link = posture.link;
+  if (link.state === 'unknown') {
+    lines.push(
+      'link: unknown — no host has started with this config directory yet; run periscope to start one',
+    );
+  } else {
+    const liveness = link.alive
+      ? `serve pid ${link.pid} is running`
+      : `serve pid ${link.pid} is gone, so this is the last thing it said`;
+    lines.push(
+      `link: ${link.state} since ${link.at} (${link.cause}${link.detail === null ? '' : `: ${link.detail}`}); ${liveness}`,
+    );
+    if (link.negotiatedVersion !== null)
+      lines.push(`protocol: v${link.negotiatedVersion} negotiated at the last accepted handshake`);
+  }
+  const credential = posture.credential;
+  switch (credential.kind) {
+    case 'paired':
+      lines.push(`credential: paired as ${posture.hostId.paired} (no expiry; rotation is re-pairing)`);
+      break;
+    case 'token':
+      lines.push(
+        `credential: signed-in token${credential.expiresAt === null ? ' (no cache yet - run periscope login)' : `, ${credential.expired ? 'EXPIRED at' : 'expires'} ${credential.expiresAt}`}`,
+      );
+      break;
+    case 'absent':
+      lines.push('credential: absent — this host dials without authentication');
+      break;
+    default:
+      lines.push(`credential: unreadable — ${credential.problem ?? ''}`);
+  }
+  lines.push(
+    `host id: ${posture.hostId.effective}` +
+      (posture.hostId.paired !== null
+        ? posture.hostId.paired === posture.hostId.configured
+          ? ' (the paired credential agrees)'
+          : ` (the paired credential's, overriding the configured ${posture.hostId.configured})`
+        : ''),
+  );
+  lines.push(
+    `workspace: ${posture.workspace.mode}${posture.workspace.branchScheme === null ? '' : `, branch scheme ${posture.workspace.branchScheme}`}`,
+  );
+  lines.push(`config file: ${posture.configFile ?? '(none: no home directory and no PERISCOPE_CONFIG_DIR)'}`);
+  for (const setting of posture.sources) {
+    // The config directory is never a config-file key (a file cannot move itself), so it is listed
+    // only when the environment set it.
+    if (setting.key === 'PERISCOPE_CONFIG_DIR' && setting.source === 'unset') continue;
+    const where =
+      setting.source === 'environment'
+        ? setting.shadowsFile
+          ? 'environment, shadowing the config file'
+          : 'environment'
+        : setting.source;
+    lines.push(`  ${setting.key} = ${setting.value ?? '(unset)'}  [${where}]`);
+  }
+  return lines;
+}

package/src/bin/reconfigure.ts

@@ -0,0 +1,266 @@
+/**
+ * A configuration change asked over the wire (`host_configure`, protocol v7): validate, write,
+ * rebuild.
+ *
+ * Split out of the composition root for the reason `workspaces.ts` gives: everything below the
+ * composition root takes its configuration as arguments, and this is the one function that
+ * reads the config file, screens a candidate posture and builds the pieces the host swaps in. It
+ * is called with the RAW environment because the file fills absences in it (`withConfigFallback`),
+ * and the same rule that governs `serve` governs a change made while serving: the environment
+ * wins per key, so a value this writes that the environment shadows is reported as overridden,
+ * never silently inert.
+ *
+ * Nothing is written until the whole candidate posture has passed the same screen start-up runs,
+ * so a half-applied set never lands on disk; and a change to a workspace root is refused while the
+ * host is busy, because a session releases through the provider that provisioned it.
+ */
+import type { HostConfigureEntry } from '../control/frames.js';
+import { isAbsolutePath, normalizePath } from '../core/paths.js';
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import {
+  claudeTranscriptResolver,
+  defaultAgentHome,
+  transcriptsRootUnder,
+} from '../host/claude-transcripts.js';
+import {
+  RESTART_KEYS,
+  WIRE_CONFIGURABLE_KEYS,
+  isWireConfigurableKey,
+  readConfigFile,
+  withConfigFallback,
+  writeConfigEntries,
+} from '../host/config-file.js';
+import type { HostReconfigured } from '../host/host.js';
+import {
+  hostConfigurationOf,
+  workspaceCapabilitiesOf,
+  workspacePostureProblem,
+  workspacesFor,
+} from './workspaces.js';
+
+/** The effective posture a merged environment describes, with absence as null. */
+interface EffectivePosture {
+  readonly workspaceRoot: string | null;
+  readonly repositoryRoot: string | null;
+  readonly branchScheme: string | null;
+  readonly workspaceKey: string | null;
+  readonly agentHome: string | null;
+  readonly controllerUrl: string | null;
+  readonly decisionUrl: string | null;
+}
+
+/**
+ * The control-plane addresses the running host actually uses: what it dialled at start. A file
+ * value that differs is written and reported as pending, never applied to the live link.
+ */
+export interface LiveAddresses {
+  readonly controllerUrl: string | null;
+  readonly decisionUrl: string | null;
+}
+
+function setOrNull(value: string | undefined): string | null {
+  return value === undefined || value === '' ? null : value;
+}
+
+function postureOf(merged: NodeJS.ProcessEnv): EffectivePosture {
+  return {
+    workspaceRoot: setOrNull(merged['PERISCOPE_WORKSPACE_ROOT']),
+    repositoryRoot: setOrNull(merged['PERISCOPE_REPOSITORY_ROOT']),
+    branchScheme: setOrNull(merged['PERISCOPE_BRANCH_SCHEME']),
+    workspaceKey: setOrNull(merged['PERISCOPE_WORKSPACE_KEY']),
+    agentHome: setOrNull(merged['PERISCOPE_AGENT_HOME']),
+    controllerUrl: setOrNull(merged['PERISCOPE_CONTROLLER_URL']),
+    decisionUrl: setOrNull(merged['PERISCOPE_DECISION_URL']),
+  };
+}
+
+/**
+ * Why a control-plane address cannot be written, or null. The link is dialled as a WebSocket and
+ * the decision endpoint is POSTed to, so each key takes the schemes its act can use and nothing
+ * else: a value that fits the other key would fail at the first act after the restart it waits for.
+ */
+/**
+ * The first thing wrong with ONE value for ONE key, or null: the per-key half of `candidateProblem`,
+ * shared with `periscope config` and the daemon's start-up read so a value the wire would refuse is
+ * refused wherever it is typed. A key this screen does not know passes; the closed key set is
+ * checked by the writer.
+ */
+export function configValueProblem(key: string, value: string): string | null {
+  switch (key) {
+    case 'PERISCOPE_CONTROLLER_URL':
+      return addressProblem(key, value, ['ws:', 'wss:']);
+    case 'PERISCOPE_DECISION_URL':
+      return addressProblem(key, value, ['http:', 'https:']);
+    case 'PERISCOPE_WORKSPACE_ROOT':
+    case 'PERISCOPE_REPOSITORY_ROOT':
+    case 'PERISCOPE_AGENT_HOME':
+      return isAbsolutePath(value) ? null : `${key} must be an absolute path — got '${value}'`;
+    case 'PERISCOPE_BRANCH_SCHEME':
+      return value.includes('{key}')
+        ? null
+        : `PERISCOPE_BRANCH_SCHEME '${value}' has no {key} placeholder — every workspace would render the same branch`;
+    default:
+      return null;
+  }
+}
+
+function addressProblem(key: string, value: string | null, schemes: readonly string[]): string | null {
+  if (value === null) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `${key} must be an absolute URL — got '${value}'`;
+  }
+  if (!schemes.includes(parsed.protocol)) {
+    return `${key} must use ${schemes.map((scheme) => scheme.slice(0, -1)).join(' or ')} — got '${value}'`;
+  }
+  return null;
+}
+
+function sameRoot(a: string | null, b: string | null): boolean {
+  if (a === null || b === null) return a === b;
+  return normalizePath(a).toLowerCase() === normalizePath(b).toLowerCase();
+}
+
+/** The wire-settable keys the environment sets: their file values are unreachable. */
+export function overriddenByEnvironment(raw: NodeJS.ProcessEnv): readonly string[] {
+  return WIRE_CONFIGURABLE_KEYS.filter((key) => {
+    const value = raw[key];
+    return value !== undefined && value !== '';
+  });
+}
+
+/**
+ * The first thing wrong with a candidate posture, or null. The same screen start-up runs
+ * (`workspacePostureProblem`) plus the rules the wire needs that start-up gets from the shell: a
+ * root must be absolute, and a scheme must render distinct branches (contain `{key}`).
+ */
+export function candidateProblem(posture: EffectivePosture): string | null {
+  for (const [key, value] of [
+    ['PERISCOPE_WORKSPACE_ROOT', posture.workspaceRoot],
+    ['PERISCOPE_REPOSITORY_ROOT', posture.repositoryRoot],
+    ['PERISCOPE_AGENT_HOME', posture.agentHome],
+  ] as const) {
+    if (value !== null && !isAbsolutePath(value)) return `${key} must be an absolute path — got '${value}'`;
+  }
+  if (posture.branchScheme !== null && !posture.branchScheme.includes('{key}')) {
+    return `PERISCOPE_BRANCH_SCHEME '${posture.branchScheme}' has no {key} placeholder — every workspace would render the same branch`;
+  }
+  const controller = addressProblem('PERISCOPE_CONTROLLER_URL', posture.controllerUrl, ['ws:', 'wss:']);
+  if (controller !== null) return controller;
+  const decision = addressProblem('PERISCOPE_DECISION_URL', posture.decisionUrl, ['http:', 'https:']);
+  if (decision !== null) return decision;
+  return workspacePostureProblem({
+    workspaceRoot: posture.workspaceRoot,
+    repositoryRoot: posture.repositoryRoot,
+    branchScheme: posture.branchScheme,
+    workspaceKey: posture.workspaceKey,
+  });
+}
+
+/**
+ * Apply the entries: screen every key, screen the candidate posture as a whole, refuse a roots
+ * change while busy, write the file once, and rebuild what the host swaps in.
+ */
+export function reconfigureHost(
+  raw: NodeJS.ProcessEnv,
+  entries: readonly HostConfigureEntry[],
+  hostBusy: boolean,
+  live?: LiveAddresses,
+): Result<HostReconfigured> {
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    if (!isWireConfigurableKey(entry.key)) {
+      return refuse(
+        'config-key-unknown',
+        `'${entry.key}' is not a key this host takes over the wire — the settable keys are ${WIRE_CONFIGURABLE_KEYS.join(', ')}`,
+      );
+    }
+    if (seen.has(entry.key)) {
+      return refuse('config-value-invalid', `'${entry.key}' is named twice in one ask`);
+    }
+    seen.add(entry.key);
+  }
+
+  const file = readConfigFile(raw);
+  if (file.problem !== null) {
+    return refuse('config-write-failed', `${file.problem} — fix or remove it before writing`);
+  }
+  const before = postureOf(withConfigFallback(raw, file.values));
+
+  // The candidate: the file with the entries applied, under the environment. An empty value is the
+  // documented twin of unset everywhere this package reads, so it removes the key like null does.
+  const nextValues: Record<string, string> = { ...file.values };
+  const writes: { key: string; value: string | null }[] = [];
+  for (const entry of entries) {
+    const value = entry.value === null || entry.value === '' ? null : entry.value;
+    if (value === null) delete nextValues[entry.key];
+    else nextValues[entry.key] = value;
+    writes.push({ key: entry.key, value });
+  }
+  // A written address is screened on its own, before the merge: the environment may shadow it today,
+  // and a bad value would still be the one the next start reads once the shadow lifts.
+  for (const write of writes) {
+    if (write.value === null) continue;
+    const problem =
+      write.key === 'PERISCOPE_CONTROLLER_URL'
+        ? addressProblem(write.key, write.value, ['ws:', 'wss:'])
+        : write.key === 'PERISCOPE_DECISION_URL'
+          ? addressProblem(write.key, write.value, ['http:', 'https:'])
+          : null;
+    if (problem !== null) return refuse('config-value-invalid', problem);
+  }
+  const merged = withConfigFallback(raw, nextValues);
+  const after = postureOf(merged);
+
+  const problem = candidateProblem(after);
+  if (problem !== null) return refuse('config-value-invalid', problem);
+
+  const rootsChange =
+    !sameRoot(before.workspaceRoot, after.workspaceRoot) ||
+    !sameRoot(before.repositoryRoot, after.repositoryRoot);
+  if (rootsChange && hostBusy) {
+    return refuse(
+      'config-host-busy',
+      'a workspace root cannot change while a session is live or opening on this host — close every session and ask again',
+    );
+  }
+
+  const written = writeConfigEntries(raw, writes);
+  if (written !== null) return refuse('config-write-failed', written);
+
+  const workspaceConfig = {
+    workspaceRoot: after.workspaceRoot,
+    repositoryRoot: after.repositoryRoot,
+    branchScheme: after.branchScheme,
+  };
+  const agentHome = after.agentHome ?? defaultAgentHome(raw);
+  const transcriptsRoot = agentHome === null ? null : transcriptsRootUnder(agentHome);
+  // The addresses in effect are what the host dialled at start; absent a caller's word, the merged
+  // view before this ask is the closest thing to it. A key whose file value differs is pending.
+  const dialled: LiveAddresses = live ?? {
+    controllerUrl: before.controllerUrl,
+    decisionUrl: before.decisionUrl,
+  };
+  const pendingRestart = RESTART_KEYS.filter((key) =>
+    key === 'PERISCOPE_CONTROLLER_URL'
+      ? after.controllerUrl !== dialled.controllerUrl
+      : after.decisionUrl !== dialled.decisionUrl,
+  );
+  return ok({
+    workspaces: workspacesFor(workspaceConfig) ?? undefined,
+    transcriptsRoot: transcriptsRoot ?? undefined,
+    bulk: transcriptsRoot === null ? undefined : claudeTranscriptResolver(transcriptsRoot),
+    linkCapabilities: workspaceCapabilitiesOf(workspaceConfig),
+    configuration: hostConfigurationOf(workspaceConfig, {
+      transcriptsRoot,
+      controllerUrl: after.controllerUrl,
+      decisionUrl: after.decisionUrl,
+      agentHome,
+    }),
+    overriddenByEnvironment: overriddenByEnvironment(raw),
+    pendingRestart,
+  });
+}