agl 1.0.17 → 21.0.2

package/ts/functions.upgradefollower.ts

@@ -0,0 +1,115 @@
+import * as plugins from './plugins.js';
+import { controllerPackageName } from '../ts_interfaces/index.js';
+import {
+  UpgradeCoordinator,
+  upgradePackageTransitionSource,
+  upgradePackageTransitionTarget,
+  upgradePackageTransitionTransactionVersion,
+  upgradeTransactionIsStalled,
+} from './classes.upgradecoordinator.js';
+import {
+  recoverStalledUpgrade,
+  type IPnpmGlobalInstallation,
+} from './classes.upgradetransaction.js';
+
+const currentCliName = String(controllerPackageName) === upgradePackageTransitionSource.packageName
+  ? upgradePackageTransitionSource.cliName
+  : upgradePackageTransitionTarget.cliName;
+
+export const followUpgradeTransaction = async (
+  coordinatorArg: UpgradeCoordinator,
+  tokenArg: string,
+  logFilePathArg: string,
+  streamLogArg: boolean,
+  installationArg: IPnpmGlobalInstallation,
+): Promise<Awaited<ReturnType<UpgradeCoordinator['readTransaction']>>> => {
+  let offset = 0;
+  let activeLogFilePath = logFilePathArg;
+  let lastRevision = -1;
+  let workerMissingSince: number | undefined;
+  while (true) {
+    const transaction = await coordinatorArg.readTransaction(tokenArg);
+    const transactionCliName = transaction.version === upgradePackageTransitionTransactionVersion
+      ? transaction.sourceCliName
+      : currentCliName;
+    const retainedLogFilePath = transaction.worker?.logFilePath;
+    if (retainedLogFilePath && retainedLogFilePath !== activeLogFilePath) {
+      activeLogFilePath = retainedLogFilePath;
+      offset = 0;
+      if (streamLogArg) {
+        process.stdout.write(
+          `${transactionCliName} upgrade: recovery worker logs: ${activeLogFilePath}\n`,
+        );
+      }
+    }
+    if (streamLogArg) {
+      const handle = await plugins.fs.promises.open(
+        activeLogFilePath,
+        plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
+      );
+      try {
+        const stats = await handle.stat();
+        if (!stats.isFile() || stats.size < offset) {
+          throw new Error(`The ${transactionCliName} upgrade log changed unexpectedly.`);
+        }
+        if (stats.size > offset) {
+          const bytes = Buffer.alloc(Math.min(stats.size - offset, 64 * 1024));
+          await handle.read(bytes, 0, bytes.byteLength, offset);
+          offset += bytes.byteLength;
+          if (!process.stdout.write(bytes)) {
+            await new Promise<void>((resolve) => process.stdout.once('drain', resolve));
+          }
+        }
+      } finally {
+        await handle.close();
+      }
+    }
+    if (transaction.revision !== lastRevision) {
+      lastRevision = transaction.revision;
+      if (streamLogArg && transaction.message) {
+        process.stdout.write(`${transactionCliName} upgrade: ${transaction.message}\n`);
+      }
+    }
+    if (transaction.terminal) return transaction;
+    if (upgradeTransactionIsStalled(transaction)) {
+      const recovered = await recoverStalledUpgrade({
+        coordinator: coordinatorArg,
+        token: tokenArg,
+        transaction,
+        installation: installationArg,
+        command: 'upgrade',
+      });
+      if (!recovered) await new Promise((resolve) => setTimeout(resolve, 5_000));
+      continue;
+    }
+    if (transaction.worker) {
+      if (await coordinatorArg.transactionWorkerIsLive(transaction)) {
+        workerMissingSince = undefined;
+      } else {
+        workerMissingSince ??= Date.now();
+        if (Date.now() - workerMissingSince > 5_000) {
+          const recovered = await recoverStalledUpgrade({
+            coordinator: coordinatorArg,
+            token: tokenArg,
+            transaction,
+            installation: installationArg,
+            command: 'upgrade',
+          });
+          if (!recovered) await new Promise((resolve) => setTimeout(resolve, 5_000));
+          continue;
+        }
+      }
+    } else {
+      workerMissingSince ??= Date.now();
+      if (Date.now() - workerMissingSince > 5_000) {
+        return await coordinatorArg.finishTransaction(
+          tokenArg,
+          false,
+          'The upgrade worker did not establish durable ownership.',
+          'No upgrade worker identity was retained before the launch deadline.',
+        );
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+};

package/ts/index.ts

@@ -1,8 +1,38 @@
-import * as early from 'early'
-early.start('plr')
-import * as plrCli from './plr.cli'
-early.stop().then(() => {
-    plrCli.run()
-})
+export * from '../ts_interfaces/index.js';
 
+export * from './00_commitinfo_data.js';
+export * from './interfaces.auth.js';
+export * from './interfaces.config.js';
+export * from './interfaces.lifecycle.js';
+export {
+  openCodeExpectedVersion,
+  openCodeUsername,
+  type IOpenCodeClientOptions,
+  type IOpenCodeConnectionConfig,
+  type IOpenCodeEventStreamOptions,
+  type IOpenCodeHealth,
+  type IOpenCodeLogEntry,
+  type IOpenCodeProcessGroupController,
+  type IOpenCodeSupervisorOptions,
+  type IOpenCodeSupervisorStatus,
+  type TOpenCodeSdkClient,
+} from './interfaces.opencode.js';
+export * from './interfaces.projects.js';
+export * from './interfaces.gitreversion.js';
 
+export * from './classes.authmodels.js';
+export * from './classes.authstore.js';
+export * from './classes.cli.js';
+export * from './classes.config.js';
+export * from './classes.controller.js';
+export * from './classes.resourcecoordinator.js';
+export * from './classes.terminalresourcehost.js';
+export * from './classes.browserresourcehost.js';
+export * from './classes.gitreversion.js';
+export * from './classes.opencodeclient.js';
+export * from './classes.opencodesupervisor.js';
+export * from './classes.passkeymanager.js';
+export * from './classes.processinspection.js';
+export * from './classes.upgradecoordinator.js';
+export * from './classes.upgradetransaction.js';
+export * from './classes.validation.js';

package/ts/interfaces.auth.ts

@@ -0,0 +1,316 @@
+import type * as plugins from './plugins.js';
+import type { IControllerRuntimeId } from '../ts_interfaces/index.js';
+import type { IControllerRuntimeConfig } from './interfaces.config.js';
+
+export type TControllerAuthLifecycleState = 'setupRequired' | 'ready';
+export type TWebAuthnCeremonyKind = 'setup' | 'authentication';
+export type TWebAuthnCeremonyState = 'pending' | 'consumed';
+/**
+ * Single source of the audit event vocabulary: the persisted-document
+ * assertion consumes this list at runtime, so a type added here is
+ * automatically storable — the two can no longer drift apart.
+ */
+export const controllerAuditEventTypes = [
+  'controller.started',
+  'controller.stopped',
+  'setup.finish',
+  'authentication.finish',
+  'authentication.logout',
+  'temppassword.create',
+  'temppassword.login',
+  'auth.resume',
+  'session.list',
+  'session.read',
+  'session.auxiliary.read',
+  'session.model.update',
+  'session.scratchpad.save',
+  'session.intelligence.ask',
+  'session.messages.page',
+  'session.message.read',
+  'session.create',
+  'session.delete',
+  'session.discard-empty',
+  'session.send',
+  'session.abort',
+  'session.rename',
+  'session.archive',
+  'session.yolo',
+  'session.builtin',
+  'slash.list',
+  'slash.execute',
+  'permission.reply',
+  'question.reply',
+  'project.list',
+  'project.create',
+  'project.remove',
+  'model.list',
+  'provider.list',
+  'provider.connection.list',
+  'provider.login.begin',
+  'provider.login.read',
+  'provider.login.cancel',
+  'provider.connection.logout',
+  'provider.connection.activate-opencode',
+  'provider.connection.ratelimits.read',
+  'provider.model.refresh.begin',
+  'provider.model.refresh.read',
+  'command.list',
+  'session.command',
+  'settings.read',
+  'settings.update',
+  'sessiongroups.read',
+  'sessiongroups.update',
+  'terminal.list',
+  'terminal.create',
+  'terminal.rename',
+  'terminal.remove',
+  'terminal.attach',
+  'resource.list',
+  'resource.create',
+  'resource.rename',
+  'resource.attach',
+  'resource.detach',
+  'resource.start',
+  'resource.stop',
+  'resource.retire',
+  'resource.browser.operation',
+  'resource.browser.view.open',
+  'resource.browser.view.close',
+  'resource.browser.view.operate',
+] as const;
+export type TControllerAuditEventType = (typeof controllerAuditEventTypes)[number];
+export type TControllerAuditOutcome = 'attempted' | 'succeeded' | 'denied' | 'failed';
+
+export type TAuthErrorCode =
+  | 'not_initialized'
+  | 'config_mismatch'
+  | 'setup_unavailable'
+  | 'setup_invalid'
+  | 'setup_expired'
+  | 'rate_limited'
+  | 'ceremony_limit'
+  | 'ceremony_invalid'
+  | 'ceremony_replayed'
+  | 'ceremony_expired'
+  | 'origin_mismatch'
+  | 'peer_mismatch'
+  | 'verification_failed'
+  | 'credential_not_found'
+  | 'concurrent_change'
+  | 'ambiguous_write'
+  | 'counter_conflict'
+  | 'invalid_project'
+  | 'invalid_resource'
+  | 'temp_password_invalid'
+  | 'temp_password_limit';
+
+export class AuthError extends Error {
+  public readonly code: TAuthErrorCode;
+
+  constructor(codeArg: TAuthErrorCode, messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'AuthError';
+    this.code = codeArg;
+  }
+}
+
+export interface IStoredPasskeyCredential {
+  id: string;
+  publicKey: string;
+  counter: number;
+  transports: plugins.simplewebauthnServer.AuthenticatorTransportFuture[];
+  deviceType: plugins.simplewebauthnServer.CredentialDeviceType;
+  backedUp: boolean;
+  createdAt: Date;
+  counterUpdateId: string;
+}
+
+export interface ISetupAuthorityState {
+  generation: string;
+  hash: string;
+  expiresAt: Date;
+}
+
+export interface IControllerAuthDocument {
+  id: string;
+  config: IControllerRuntimeConfig;
+  authState: TControllerAuthLifecycleState;
+  setup: ISetupAuthorityState | null;
+  webauthnUserId: string;
+  credentials: IStoredPasskeyCredential[];
+}
+
+export interface IWebAuthnCeremonyDocument {
+  id: string;
+  kind: TWebAuthnCeremonyKind;
+  state: TWebAuthnCeremonyState;
+  peerId: string;
+  challenge: string;
+  origin: string;
+  rpId: string;
+  userId: string;
+  createdAt: Date;
+  expiresAt: Date;
+  consumedAt?: Date;
+  consumedNonce?: string;
+  setupGeneration?: string;
+  setupHash?: string;
+}
+
+export interface IWebAuthnSetupCeremonyDocument extends IWebAuthnCeremonyDocument {
+  kind: 'setup';
+  setupGeneration: string;
+  setupHash: string;
+}
+
+export interface IWebAuthnAuthenticationCeremonyDocument extends IWebAuthnCeremonyDocument {
+  kind: 'authentication';
+  setupGeneration?: never;
+  setupHash?: never;
+}
+
+export interface ISetupAuthority {
+  setupCode: string;
+  generation: string;
+  expiresAt: Date;
+}
+
+export interface IControllerAuditEvent {
+  id: string;
+  controllerId: string;
+  timestamp: Date;
+  type: TControllerAuditEventType;
+  outcome: TControllerAuditOutcome;
+  operationId?: string;
+  peerId?: string;
+  credentialId?: string;
+  sessionId?: IControllerRuntimeId;
+  requestId?: IControllerRuntimeId;
+}
+
+export interface IControllerTempPasswordDocument {
+  id: string;
+  controllerId: string;
+  /** base64url SHA-256 of the plaintext; the plaintext is never stored. */
+  secretHash: string;
+  createdAt: Date;
+  expiresAt: Date;
+}
+
+export interface IMintedTempPassword {
+  /** Plaintext credential, shown once by the CLI and never persisted. */
+  password: string;
+  credentialId: string;
+  expiresAt: Date;
+}
+
+export interface IRecordAuditEventInput {
+  timestamp?: Date;
+  type: TControllerAuditEventType;
+  outcome: TControllerAuditOutcome;
+  operationId?: string;
+  peerId?: string;
+  credentialId?: string;
+  sessionId?: IControllerRuntimeId;
+  requestId?: IControllerRuntimeId;
+}
+
+export interface IConsumeCeremonyOptions {
+  ceremonyId: string;
+  kind: TWebAuthnCeremonyKind;
+  peerId: string;
+  origin: string;
+  rpId: string;
+  userId: string;
+  now: Date;
+}
+
+export interface IAuthStore {
+  init(): Promise<void>;
+  close(): Promise<void>;
+  getRuntimeConfig(controllerPortArg: number): Promise<IControllerRuntimeConfig | undefined>;
+  resolveOrCreateRuntimeConfig(
+    runtimeConfigArg: IControllerRuntimeConfig,
+  ): Promise<IControllerAuthDocument>;
+  rotateSetupAuthority(): Promise<ISetupAuthority | null>;
+  getState(): Promise<IControllerAuthDocument>;
+  assertSetupAuthority(
+    setupCodeArg: string,
+    ceremonyArg?: IWebAuthnSetupCeremonyDocument,
+    nowArg?: Date,
+  ): Promise<IControllerAuthDocument>;
+  countActiveCeremonies(kindArg: TWebAuthnCeremonyKind, nowArg: Date): Promise<number>;
+  createCeremony(
+    ceremonyArg: IWebAuthnCeremonyDocument,
+  ): Promise<IWebAuthnCeremonyDocument>;
+  assertPendingCeremony(
+    optionsArg: IConsumeCeremonyOptions,
+  ): Promise<IWebAuthnCeremonyDocument>;
+  consumeCeremony(optionsArg: IConsumeCeremonyOptions): Promise<IWebAuthnCeremonyDocument>;
+  commitFirstCredential(
+    ceremonyArg: IWebAuthnSetupCeremonyDocument,
+    credentialArg: IStoredPasskeyCredential,
+  ): Promise<IControllerAuthDocument>;
+  updateCounter(
+    credentialIdArg: string,
+    expectedCounterArg: number,
+    newCounterArg: number,
+  ): Promise<IStoredPasskeyCredential>;
+  recordAuditEvent(eventArg: IRecordAuditEventInput): Promise<IControllerAuditEvent>;
+}
+
+export interface IWebAuthnServerImplementation {
+  generateRegistrationOptions: typeof plugins.simplewebauthnServer.generateRegistrationOptions;
+  verifyRegistrationResponse: typeof plugins.simplewebauthnServer.verifyRegistrationResponse;
+  generateAuthenticationOptions: typeof plugins.simplewebauthnServer.generateAuthenticationOptions;
+  verifyAuthenticationResponse: typeof plugins.simplewebauthnServer.verifyAuthenticationResponse;
+}
+
+export interface IPasskeyManagerOptions {
+  store: IAuthStore;
+  relyingPartyName?: string;
+  webAuthn?: IWebAuthnServerImplementation;
+  now?: () => Date;
+  setupAttemptLimit?: number;
+  setupAttemptWindowMs?: number;
+  authenticationAttemptLimitPerPeer?: number;
+  authenticationAttemptWindowMs?: number;
+  maxActiveSetupCeremonies?: number;
+  maxActiveAuthenticationCeremonies?: number;
+}
+
+export interface ISetupBeginOptions {
+  peerId: string;
+  origin: string;
+  setupCode: string;
+}
+
+export interface ISetupFinishOptions extends ISetupBeginOptions {
+  ceremonyId: string;
+  response: plugins.simplewebauthnServer.RegistrationResponseJSON;
+}
+
+export interface IAuthenticationBeginOptions {
+  peerId: string;
+  origin: string;
+}
+
+export interface IAuthenticationFinishOptions extends IAuthenticationBeginOptions {
+  ceremonyId: string;
+  response: plugins.simplewebauthnServer.AuthenticationResponseJSON;
+}
+
+export interface ISetupBeginResult {
+  ceremonyId: string;
+  options: plugins.simplewebauthnServer.PublicKeyCredentialCreationOptionsJSON;
+}
+
+export interface IAuthenticationBeginResult {
+  ceremonyId: string;
+  options: plugins.simplewebauthnServer.PublicKeyCredentialRequestOptionsJSON;
+}
+
+export interface IAuthenticationResult {
+  authenticated: true;
+  credentialId: string;
+}

package/ts/interfaces.config.ts

@@ -0,0 +1,37 @@
+export type TControllerTlsMode = 'local' | 'proxy';
+
+export interface IControllerRuntimeConfig {
+  controllerPort: number;
+  publicOrigin: string;
+  rpId: string;
+  workspaceDirectory: string;
+  /**
+   * Root directory that bounds all registered projects. Absent only in
+   * documents persisted before v2; config resolution adopts a value exactly
+   * once (from --projects-root, else the workspace directory), after which it
+   * is immutable like every other boundary.
+   */
+  projectsRoot?: string;
+  opencodePort: number;
+  tlsMode: TControllerTlsMode;
+}
+
+export interface IControllerRuntimeOverrides {
+  controllerPort: number;
+  publicOrigin?: string;
+  rpId?: string;
+  workspaceDirectory?: string;
+  projectsRoot?: string;
+  opencodePort?: number;
+  behindTlsProxy?: boolean;
+}
+
+export interface IControllerDatabaseConfig {
+  /** external server URL; absent = embedded smartdb engine */
+  mongoDbUrl?: string;
+  mongoDbName: string;
+  /** storage directory for the embedded engine; set when mongoDbUrl is absent */
+  embeddedDataDirectory?: string;
+  /** previous installed default, logically migrated only for the implicit installed database */
+  legacyEmbeddedDataDirectory?: string;
+}