@ours.network/install 1.2.0-nightly.2 → 1.2.1-nightly.2

package/lib/server-onboarding.mjs

@@ -0,0 +1,113 @@
+/** Human bootstrap and local client handoff through the existing owner interfaces. */
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { installationPaths } from './plan.mjs';
+import { validateHostProfile } from './target.mjs';
+
+export function validateIdentityName(name) {
+  if (typeof name !== 'string' || [...name].length < 1 || [...name].length > 64 || name !== name.normalize('NFC')
+      || /[\\/\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u.test(name)
+      || ['.', '..', 'contact-book', 'root.json', 'bindings.json'].includes(name)) {
+    throw new Error('Invalid Human identity name; use 1–64 NFC characters without reserved names or path/control characters');
+  }
+}
+function privatePath(path, directory = false) {
+  const stat = lstatSync(path);
+  if (!(directory ? stat.isDirectory() : stat.isFile()) || realpathSync(path) !== path
+      || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || (!directory && stat.nlink !== 1)) {
+    throw new Error('Onboarding requires an owned private ' + (directory ? 'directory' : 'regular credential file'));
+  }
+  return stat;
+}
+function validateRecord(record) {
+  if (!record || !['packages', 'docker'].includes(record.mode) || typeof record.root !== 'string'
+      || !isAbsolute(record.root) || resolve(record.root) !== record.root
+      || !Number.isInteger(record.port) || record.port < 1 || record.port > 65535) throw new Error('Invalid local server selection');
+  validateHostProfile({ endpoint: `http://127.0.0.1:${record.port}`, expectedInstanceId: record.instanceId, credentialPath: join(record.root, 'client', 'credential') });
+}
+
+export function createServerOnboarding(effects, { compose, localEnv, bin }) {
+  async function identityCommand(record, args) {
+    const result = record.mode === 'docker'
+      ? await compose(record, ['exec', '-T', 'daemon', 'node', '/opt/ours/node_modules/@ours.network/cli/dist/cli.js', ...args, '--config', '/var/lib/ours/config.json', '--state-dir', '/var/lib/ours', '--json'])
+      : await effects.run(bin(record, 'ours'), [...args, '--config', record.configPath, '--state-dir', installationPaths(record).daemon, '--json'], { env: localEnv(record) });
+    if (result.code !== undefined && result.code !== 0) throw new Error('Owner identity operation failed');
+    try { return JSON.parse(result.stdout); }
+    catch { throw new Error('Owner identity operation returned malformed JSON'); }
+  }
+  async function identities(record) {
+    const rows = await identityCommand(record, ['identity', 'list']);
+    if (!Array.isArray(rows) || rows.some(row => !row || typeof row.name !== 'string'
+        || (!['root', 'role'].includes(row.kind) && !['reconciling', 'awaiting-root', 'migration-failed', 'refresh-failed'].includes(row.status))
+        || (row.kind && (typeof row.cid !== 'string' || !row.cid)))) throw new Error('Owner identity list is malformed');
+    const roots = rows.filter(row => row.kind === 'root');
+    if (roots.length > 1) throw new Error('Owner identity list contains multiple Human roots');
+    return { rows, root: roots[0] };
+  }
+  function retained({ rows, root }) {
+    effects.out?.(`Retained ${rows.length} existing ${rows.length === 1 ? 'identity' : 'identities'}; Human identity: ${root.name}.`);
+    return { name: root.name, cid: root.cid, created: false };
+  }
+  return {
+    async serverEnsureIdentity(record, name) {
+      validateRecord(record);
+      validateIdentityName(name);
+      const prior = await identities(record);
+      if (prior.root) return retained(prior);
+      if (prior.rows.some(row => row.name === name)) throw new Error('Requested Human identity name already exists; no identity was changed');
+      effects.out?.(`Creating Human identity ${name}; retaining ${prior.rows.length} existing identities.`);
+      try {
+        await identityCommand(record, ['identity', 'create-root', '--name', name, '--skip-if-root-exists', 'true']);
+      } catch (error) {
+        // ROOT_EXISTS is currently a CLI error. A concurrent creator is safe only
+        // when the authoritative list now contains a root; other errors stay errors.
+        const after = await identities(record);
+        if (after.root) return retained(after);
+        throw error;
+      }
+      const after = await identities(record);
+      if (!after.root) throw new Error('Human identity creation completed without a visible root');
+      if (after.root.name !== name) return retained(after);
+      effects.out?.(`Human identity ${after.root.name} is ready.`);
+      return { name: after.root.name, cid: after.root.cid, created: true };
+    },
+    async prepareLocalClient(record, integrations, fleetSettingsPath) {
+      validateRecord(record);
+      if (!Array.isArray(integrations) || !integrations.length || new Set(integrations).size !== integrations.length
+          || integrations.some(name => !['codex', 'claude-code', 'fleet'].includes(name))) throw new Error('Client integrations must select codex, claude-code and/or fleet');
+      if (fleetSettingsPath !== undefined) {
+        if (typeof fleetSettingsPath !== 'string' || !isAbsolute(fleetSettingsPath) || resolve(fleetSettingsPath) !== fleetSettingsPath) throw new Error('Fleet settings path must be absolute');
+        const settings = JSON.parse(readFileSync(fleetSettingsPath, 'utf8'));
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Fleet settings must be a JSON object');
+      }
+      const endpoint = `http://127.0.0.1:${record.port}`;
+      const current = effects.readManagedClientProfile();
+      if (current && (current.endpoint !== endpoint || current.expectedInstanceId !== record.instanceId)) throw new Error('Managed client already selects another server; no credential was issued');
+      privatePath(record.root, true);
+      const root = join(record.root, 'client');
+      if (!existsSync(root)) mkdirSync(root, { mode: 0o700 });
+      privatePath(root, true);
+      const stage = mkdtempSync(join(root, '.pending-'));
+      const published = join(root, 'issued-' + randomUUID());
+      const credential = join(stage, 'credential');
+      try {
+        effects.out?.('Issuing a separate local client credential with the retained server authority.');
+        try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
+        catch { throw new Error('Client credential issuance failed; existing profiles were retained'); }
+        const stat = privatePath(credential);
+        if (stat.size > 4096 || !readFileSync(credential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
+        const profile = {
+          ...validateHostProfile({ endpoint, expectedInstanceId: record.instanceId, credentialPath: join(published, 'credential') }),
+          installer: { integrations: [...integrations], ...(fleetSettingsPath !== undefined ? { fleetSettingsPath } : {}) },
+        };
+        writeFileSync(join(stage, 'profile.json'), JSON.stringify(profile, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        // Publish the complete pair in one rename. Managed-default activation and
+        // package/source selection remain the normal client installer's job.
+        renameSync(stage, published);
+        effects.out?.('Local client profile is ready for authenticated client setup.');
+        return { configPath: join(published, 'profile.json'), profile };
+      } finally { rmSync(stage, { recursive: true, force: true }); }
+    },
+  };
+}

package/lib/setup-options.mjs

@@ -0,0 +1,157 @@
+import { join, resolve } from 'node:path';
+
+const scopes = ['all', 'server', 'client'];
+const integrations = ['codex', 'claude-code', 'fleet'];
+const valueFlags = new Map(Object.entries({
+  '--scope': 'scope', '--action': 'operation', '--mode': 'mode', '--state-dir': 'stateDir',
+  '--identity-name': 'identityName', '--integrations': 'integrations', '--fleet-settings': 'fleetSettingsPath',
+  '--config': 'config', '--sources': 'sources', '--port': 'port', '--cowork-port': 'coworkPort', '--messenger-port': 'messengerPort',
+}));
+const boolFlags = new Map([['--compatible', 'compatible'], ['--dry-run', 'dryRun'], ['--migrate', 'migrate']]);
+const allowed = new Set([...valueFlags.values(), ...boolFlags.values(), 'interactive', 'explicitPorts']);
+const defaults = { port: 3050, coworkPort: 3052, messengerPort: 8420 };
+const paths = ['stateDir', 'config', 'sources', 'fleetSettingsPath'];
+const nonempty = value => typeof value === 'string' && value.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+
+export function recommendedMode({ platform, arch, release = '' } = {}) {
+  if (platform === 'linux' && /microsoft|wsl/i.test(release)) return { mode: 'docker', reason: 'Docker is recommended on Windows and WSL.' };
+  if (platform === 'linux' && arch === 'x64') return { mode: 'packages', reason: 'Native packages are recommended on Linux x64 with a systemd user manager.' };
+  if (platform === 'darwin') return { mode: 'docker', reason: 'Docker is recommended on macOS.' };
+  if (platform === 'win32') return { mode: 'docker', reason: 'Docker is recommended on Windows; run the installer inside WSL with Docker Desktop.' };
+  return { mode: 'docker', reason: 'Docker is recommended for this platform.' };
+}
+
+export function validateSetupOptions(input, { interactive = input?.interactive === true } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Setup options must be an object');
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`Unknown setup option: ${key}`);
+  const options = { ...input, scope: input.scope ?? 'all', operation: input.operation ?? 'install', interactive };
+  if (!scopes.includes(options.scope)) throw new Error('Scope must be all, server, or client');
+  if (!['install', 'update'].includes(options.operation)) throw new Error('Operation must be install or update');
+  const server = options.scope !== 'client';
+  const client = options.scope !== 'server';
+  const missing = [];
+  if (server) for (const [key, flag] of [['mode', '--mode'], ['stateDir', '--state-dir'], ['identityName', '--identity-name']]) if (!nonempty(options[key])) missing.push(flag);
+  if (client && options.integrations === undefined) missing.push('--integrations (use none to skip)');
+  if (!server && !nonempty(options.config)) missing.push('--config');
+  if (server && options.operation === 'update' && options.compatible !== true) missing.push('--compatible');
+  if (Array.isArray(options.integrations) && options.integrations.includes('fleet') && !interactive && !nonempty(options.fleetSettingsPath)) missing.push('--fleet-settings');
+  if (missing.length) throw new Error(`Missing required setup options: ${missing.join(', ')}`);
+  if (options.mode === 'native') options.mode = 'packages';
+  if (server && !['packages', 'docker'].includes(options.mode)) throw new Error('Mode must be packages (or native) or docker');
+  if (server && options.config !== undefined) throw new Error('--config is only valid for client scope');
+  if (!server) for (const key of ['mode', 'stateDir', 'identityName', ...Object.keys(defaults), 'compatible', 'migrate']) {
+    if (options[key] !== undefined) throw new Error(`${key} is only valid for server or all scope`);
+  }
+  if (!client && (options.integrations !== undefined || options.fleetSettingsPath !== undefined)) throw new Error('--integrations and --fleet-settings require all or client scope');
+  if (options.integrations !== undefined) {
+    if (!Array.isArray(options.integrations) || options.integrations.some(name => !integrations.includes(name)) || new Set(options.integrations).size !== options.integrations.length) throw new Error('Integrations must be unique codex, claude-code, fleet, or none');
+    options.integrations = [...options.integrations];
+  }
+  if (options.fleetSettingsPath !== undefined && !options.integrations?.includes('fleet')) throw new Error('--fleet-settings requires the fleet integration');
+  for (const key of paths) if (options[key] !== undefined && !nonempty(options[key])) throw new Error(`Invalid path for ${key}`);
+  for (const key of ['compatible', 'migrate']) if (options[key] !== undefined && typeof options[key] !== 'boolean') throw new Error(`${key} must be a boolean`);
+  if (server) {
+    options.identityName = options.identityName.trim();
+    for (const [key, fallback] of Object.entries(defaults)) {
+      options[key] ??= fallback;
+      if (!Number.isInteger(options[key]) || options[key] < 1 || options[key] > 65535) throw new Error(`${key} must be an integer port between 1 and 65535`);
+    }
+    if (new Set(Object.keys(defaults).map(key => options[key])).size !== 3) throw new Error('Server ports must be distinct');
+  }
+  options.explicitPorts ??= [];
+  if (!Array.isArray(options.explicitPorts) || options.explicitPorts.some(key => !Object.hasOwn(defaults, key)) || new Set(options.explicitPorts).size !== options.explicitPorts.length || (!server && options.explicitPorts.length)) throw new Error('Invalid explicitPorts selection');
+  options.explicitPorts = [...options.explicitPorts];
+  return options;
+}
+
+function expandPaths(options, home) {
+  const output = { ...options };
+  for (const key of paths) if (nonempty(output[key])) {
+    const value = output[key];
+    if (value === '~' || value.startsWith('~/')) {
+      if (!nonempty(home)) throw new Error('Home directory is required to expand ~/ paths');
+      output[key] = resolve(home, value === '~' ? '' : value.slice(2));
+    } else output[key] = resolve(value);
+  }
+  return output;
+}
+
+export function parseSetupArgs(argv, { home } = {}) {
+  if (!Array.isArray(argv) || !argv.every(arg => typeof arg === 'string')) throw new Error('Arguments must be strings');
+  const options = { interactive: false, explicitPorts: [] };
+  const seen = new Set();
+  const positional = [];
+  const put = (key, value) => {
+    if (seen.has(key)) throw new Error(`Duplicate or conflicting setup option: ${key}`);
+    seen.add(key); options[key] = value;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('-')) { positional.push(arg); continue; }
+    const equal = arg.indexOf('=');
+    const flag = equal < 0 ? arg : arg.slice(0, equal);
+    if (boolFlags.has(flag)) {
+      if (equal >= 0) throw new Error(`${flag} takes no value`);
+      put(boolFlags.get(flag), true); continue;
+    }
+    if (!valueFlags.has(flag)) throw new Error(`Unknown setup flag: ${flag}`);
+    const value = equal < 0 ? argv[++i] : arg.slice(equal + 1);
+    if (!nonempty(value) || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    const key = valueFlags.get(flag);
+    if (key === 'integrations') put(key, value === 'none' ? [] : value.split(',').map(item => item.trim()));
+    else if (Object.hasOwn(defaults, key)) {
+      if (!/^[1-9]\d*$/.test(value)) throw new Error(`${flag} requires an integer port`);
+      put(key, Number(value)); options.explicitPorts.push(key);
+    } else put(key, value);
+  }
+  if (positional.length && scopes.includes(positional[0])) put('scope', positional.shift());
+  if (positional.length && ['install', 'update'].includes(positional[0])) put('operation', positional.shift());
+  if (positional.length) throw new Error(`Unexpected setup argument: ${positional.join(' ')}`);
+  return validateSetupOptions(expandPaths(options, home), { interactive: false });
+}
+
+export async function collectSetupOptions(effects) {
+  if (effects.interactive !== true) throw new Error('Interactive setup requires a TTY; provide the complete CLI options instead');
+  const options = { interactive: true, explicitPorts: [] };
+  options.scope = (await effects.askLine('Set up all, server, or client? ', 'all')).trim();
+  if (!scopes.includes(options.scope)) throw new Error('Scope must be all, server, or client');
+  let existing;
+  if (options.scope !== 'client') {
+    options.stateDir = await effects.askLine('Private installation root: ', join(effects.home, '.ours-install'));
+    options.stateDir = expandPaths({ stateDir: options.stateDir }, effects.home).stateDir;
+    existing = effects.readJson(join(options.stateDir, 'installation.json'));
+    const legacyRoot = join(effects.home, '.ours');
+    const legacy = !existing ? effects.readJson(join(legacyRoot, 'config.json')) : null;
+    if (legacy?.stateDir === legacyRoot) throw new Error(`An existing global daemon was found at ${legacyRoot}, without a managed installation record for the selected root. This form cannot migrate that installation yet. Keep its state; use explicit CLI presets with a different empty directory only if you intend a separate installation.`);
+  }
+  options.operation = (await effects.askLine('Install or update? ', existing ? 'update' : 'install')).trim();
+  if (options.scope !== 'client') {
+    const recommendation = recommendedMode({ ...effects.platform, arch: effects.platform?.arch ?? process.arch });
+    effects.out(`Detected ${effects.platform?.platform ?? 'unknown'} / ${effects.platform?.arch ?? process.arch}. ${recommendation.reason}`);
+    const defaultMode = existing?.mode ?? recommendation.mode;
+    options.mode = await effects.askLine('Runtime mode (native or docker): ', defaultMode === 'packages' ? 'native' : defaultMode);
+    options.identityName = await effects.askLine('What name should others see? ', existing?.messengerIdentity ?? effects.username?.() ?? 'me');
+    for (const [key, fallback] of Object.entries(defaults)) {
+      const label = { port: 'Daemon', coworkPort: 'Cowork', messengerPort: 'Messenger' }[key];
+      const value = await effects.askLine(`${label} port: `, String(existing?.[key] ?? fallback));
+      if (!/^[1-9]\d*$/.test(value)) throw new Error(`${label} port must be an integer`);
+      options[key] = Number(value); options.explicitPorts.push(key);
+    }
+    if (options.operation === 'update') options.compatible = await effects.ask('Confirm that the selected update is compatible with retained state?', false);
+  } else options.config = await effects.askLine('Prepared client profile path: ', join(effects.home, '.ours-client', 'profile.json'));
+  if (options.scope !== 'server') {
+    const detected = typeof effects.detectHarnesses === 'function' ? await effects.detectHarnesses() : [];
+    options.integrations = [];
+    for (const name of integrations) if (await effects.ask(`Install ${name}?`, name === 'fleet' || detected.some(item => item.name === name && item.status === 'ok'))) options.integrations.push(name);
+    if (options.integrations.includes('fleet')) {
+      const path = await effects.askLine('Fleet settings file (leave empty for the interactive Fleet wizard): ', '');
+      if (path.trim()) options.fleetSettingsPath = path;
+    }
+  }
+  const sources = await effects.askLine('Source policy override (leave empty for the packaged release): ', '');
+  if (sources.trim()) options.sources = sources;
+  const validated = validateSetupOptions(expandPaths(options, effects.home), { interactive: true });
+  effects.out(`Setup: ${validated.operation} ${validated.scope}${validated.mode ? ` using ${validated.mode} in ${validated.stateDir}` : ` from ${validated.config}`}; integrations: ${validated.integrations?.join(', ') || 'none'}.`);
+  if (!await effects.ask('Continue with this setup?', false)) throw new Error('Setup cancelled; nothing was changed');
+  return validated;
+}

package/lib/setup.mjs

@@ -0,0 +1,145 @@
+import { join } from 'node:path';
+import { parseSetupArgs, collectSetupOptions, validateSetupOptions } from './setup-options.mjs';
+import { parseNetworkArgs, validateHostProfile, InstallUsageError } from './target.mjs';
+import { validateInstallation } from './plan.mjs';
+import { runServerCommand, runClientCommand } from './orchestrate.mjs';
+import { banner, heading, info, ok, warn, progress } from './ui.mjs';
+import { isCancel } from './prompt.mjs';
+import { USAGE } from './usage.mjs';
+import { validateIdentityName } from './server-onboarding.mjs';
+import { validateFleetSettings } from './fleet-settings.mjs';
+
+const maintenance = new Set(['status', 'start', 'stop', 'restart', 'rebuild', 'access-issue', 'access-replace', 'backup', 'restore', 'reset']);
+const clientPackages = integrations => [...new Set(['sdk', ...(integrations.includes('fleet') ? ['cli'] : []), ...integrations])];
+
+export function completeReleasePolicy(retained, supplied) {
+  if (retained?.release) {
+    return { release: retained.release, packages: Object.fromEntries(Object.entries(retained.release.packages).map(([name, entry]) => [name, { type: 'npm', version: entry.version }])) };
+  }
+  if (supplied) return supplied;
+  throw new InstallUsageError('This development installation needs its full --sources policy to configure clients; server-only selections cannot supply client packages');
+}
+
+function readObject(effects, path, label) {
+  const value = effects.readJson(path);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new InstallUsageError(`${label} must be a readable JSON object: ${path}`);
+  return value;
+}
+
+/** Read-only validation of the complete plan, before any locks, installs or service changes. */
+export async function prepareSetupPlan(options, effects) {
+  options = validateSetupOptions(options, { interactive: options.interactive });
+  if (effects.platform?.platform === 'win32') throw new InstallUsageError('Run ours-install inside WSL with Docker Desktop integration on Windows. Direct Windows Node installations are not supported.');
+  const plan = { ...options };
+  if (options.scope !== 'server' && options.integrations.length) {
+    for (const name of ['OURS_API_TOKEN', 'OURS_PORT', 'OURS_STATE_DIR', 'OURS_DAEMON_ID']) {
+      if (effects.env?.[name]?.trim()) throw new InstallUsageError(`${name} conflicts with the selected client profile. Clear this override before full-stack/client setup; nothing was changed.`);
+    }
+  }
+  if (options.scope !== 'client') validateIdentityName(options.identityName);
+  if (options.fleetSettingsPath) validateFleetSettings(readObject(effects, options.fleetSettingsPath, 'Fleet settings'));
+  const policy = options.sources ? readObject(effects, options.sources, 'Source policy') : effects.packagedSourcePolicy();
+  plan.sourcePolicy = policy;
+  if (options.scope !== 'client') {
+    const value = effects.readJson(join(options.stateDir, 'installation.json'));
+    if (value) {
+      plan.existing = validateInstallation(value, options.stateDir);
+      if (options.mode !== plan.existing.mode) throw new InstallUsageError('The selected mode conflicts with the retained installation; choose its existing mode or a separate empty directory');
+      for (const key of ['port', 'coworkPort', 'messengerPort']) {
+        if (options.explicitPorts?.includes(key) && options[key] !== plan.existing[key]) throw new InstallUsageError(`${key} conflicts with the retained installation`);
+        plan[key] = plan.existing[key];
+      }
+      if (options.operation === 'install') {
+        const retained = readObject(effects, plan.existing.sourcesPath, 'Retained source policy');
+        plan.sourcePolicy = options.scope === 'server' || !options.integrations?.length ? retained : completeReleasePolicy(retained, options.sources ? policy : null);
+      }
+    } else if (options.operation === 'update') {
+      throw new InstallUsageError('Update requires an existing installation.json; choose install for a new installation');
+    }
+    // Reject a local client already attached to another server before changing the server.
+    const saved = options.scope === 'all' && options.integrations.length ? effects.readManagedClientProfile() : null;
+    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== `http://127.0.0.1:${plan.port}`)) {
+      throw new InstallUsageError('This user already has clients attached to a different server; their saved connection was not changed');
+    }
+  } else {
+    const profile = validateHostProfile(readObject(effects, options.config, 'Client profile'));
+    if (!profile) throw new InstallUsageError('Client profile must contain endpoint, expectedInstanceId and credentialPath');
+    if (!effects.readText(profile.credentialPath)?.trim()) throw new InstallUsageError('Client credential file is missing or empty');
+    plan.profile = profile;
+    const saved = effects.readManagedClientProfile();
+    if (saved && (saved.endpoint !== profile.endpoint || saved.expectedInstanceId !== profile.expectedInstanceId)) throw new InstallUsageError('Managed clients already select another server; existing connection was not changed');
+    if (saved && options.operation === 'install' && !options.sources) plan.sourcePolicy = readObject(effects, saved.installer.sourcesPath, 'Retained client source policy');
+  }
+  // Dry-run never spawns a resolver or acquires an installation lock.
+  if (!options.dryRun) {
+    if (options.scope === 'all' && options.operation === 'update' && options.integrations.length) {
+      const running = await effects.serverLifecycle(plan.existing, 'status', ['daemon']);
+      if (!running.includes('daemon')) throw new InstallUsageError('Full-stack update requires the selected daemon to be running for client verification. Start it first, or use server update to preserve its stopped state.');
+    }
+    if (options.scope !== 'client') await effects.resolveSourcePolicy(plan.sourcePolicy, 'server');
+    if (options.scope !== 'server' && options.integrations.length) await effects.resolveSourcePolicy(plan.sourcePolicy, 'client', clientPackages(options.integrations));
+  }
+  return plan;
+}
+
+export async function executeSetupPlan(plan, effects, { server = runServerCommand, client = runClientCommand } = {}) {
+  if (!plan.interactive) effects.out(banner());
+  effects.out(heading(`${plan.operation === 'update' ? 'Update' : 'Install'} ours.network`));
+  effects.out(info(`Scope: ${plan.scope}; ${plan.scope === 'client' ? `profile: ${plan.config}` : `mode: ${plan.mode === 'packages' ? 'native' : 'docker'}; directory: ${plan.stateDir}`}`));
+  if (plan.scope !== 'server') effects.out(info(`Client integrations: ${plan.integrations.join(', ') || 'none'}`));
+  if (plan.dryRun) {
+    effects.out(info('Preview only. No packages, identities, credentials or services will be changed.'));
+    if (plan.scope !== 'client') effects.out(info('Server: prerequisites → runtime preparation/update → retained identity/state restoration → readiness.'));
+    if (plan.scope !== 'server' && plan.integrations.length) effects.out(info('Clients: private connection → exact packages → selected integrations → Fleet settings when selected.'));
+    return 0;
+  }
+  let clientConfig = plan.config;
+  let clientPolicy = plan.sourcePolicy;
+  if (plan.scope !== 'client') {
+    effects.out(heading(plan.operation === 'update' ? 'Server update and identity restoration' : 'Server installation'));
+    const result = await server({ ...plan, role: 'server', operation: plan.operation, sourcePolicy: plan.sourcePolicy }, effects);
+    if (result !== 0) return result;
+    const record = validateInstallation(effects.readJson(join(plan.stateDir, 'installation.json')), plan.stateDir);
+    if (plan.operation === 'update') {
+      effects.out(progress(0, 1, 'Retained identities', 'Verify the Human identity after state restoration; existing names and keys are retained.'));
+      const running = await effects.serverLifecycle(record, 'status', ['daemon']);
+      if (running.includes('daemon')) {
+        await effects.serverEnsureIdentity(record, plan.identityName);
+        effects.out(ok('Retained identities verified.'));
+      } else effects.out(info('Daemon remains stopped; stored identities are retained and will restore on the next start.'));
+    }
+    if (plan.scope === 'all' && plan.integrations.length) {
+      clientPolicy = completeReleasePolicy(readObject(effects, record.sourcesPath, 'Server source policy'), plan.sourcePolicy);
+      effects.out(heading('Connect local clients'));
+      const handoff = await effects.prepareLocalClient(record, plan.integrations, plan.fleetSettingsPath);
+      clientConfig = handoff.configPath;
+    }
+  }
+  if (plan.scope !== 'server' && plan.integrations.length) {
+    const result = await client({ role: 'client', operation: 'install', config: clientConfig,
+      integrations: plan.integrations, fleetSettingsPath: plan.fleetSettingsPath, sourcePolicy: clientPolicy,
+      preset: true, nonInteractive: !plan.interactive }, effects);
+    if (result !== 0) return result;
+  }
+  effects.out(ok(`Requested ${plan.operation} completed. Existing identities were retained.`));
+  if (plan.integrations?.includes('fleet')) effects.out(info('Fleet is configured but stopped. Review its settings, then run ours-fleet doctor, ours-fleet config and ours-fleet up.'));
+  return 0;
+}
+
+/** The sole executable entry: manual answers and CLI presets share one plan/executor. */
+export async function runSetup(argv, effects) {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) { effects.out(USAGE); return 0; }
+    if (argv.length === 1 && ['--version', '-V'].includes(argv[0])) { effects.out(effects.version ?? 'unknown'); return 0; }
+    if (argv[0] === 'server' && maintenance.has(argv[1])) return await runServerCommand(parseNetworkArgs(argv), effects);
+    if (!argv.length && effects.env?.OURS_ASSUME_YES) throw new InstallUsageError('OURS_ASSUME_YES cannot fill an interactive setup plan. Supply complete CLI presets for unattended installation.');
+    if (!argv.length) { effects.out(banner()); effects.out(heading('Interactive setup')); }
+    const options = argv.length ? parseSetupArgs(argv, { home: effects.home }) : await collectSetupOptions(effects);
+    const plan = await prepareSetupPlan(options, effects);
+    return await executeSetupPlan(plan, effects);
+  } catch (error) {
+    if (isCancel(error)) { effects.out(warn('Installation cancelled.')); return 130; }
+    effects.out(warn(`ours-install: ${error.message}`));
+    return 2;
+  }
+}

package/lib/usage.mjs

@@ -1,55 +1,58 @@
-// ours-install v3 — the help text.
-//
-// It lives here rather than in the bin because `--help` is a behaviour with a
-// contract (the flags it names must be the flags target.mjs accepts), and a bin
-// that is three lines long cannot be the place a contract is asserted.
+// Public setup and maintenance commands.
+export const USAGE = `ours-install — interactive setup or complete CLI presets.
 
-export const USAGE = `ours-install — the unified ours.network stack installer.
+  ours-install
+    Opens the console form. Choose all (server + clients), server, or client;
+    runtime, installation directory, identity, integrations and Fleet settings.
+    Linux x64 recommends native; macOS/Windows recommend Docker. Windows uses WSL.
 
-  Selected network installation (uses the packaged compatible source policy):
-    ours-install server install --mode packages|docker [--sources PATH] --state-dir PATH
-    ours-install server status|start|stop|restart --state-dir PATH
-    ours-install server rebuild --state-dir PATH
-    ours-install server update --state-dir PATH [--sources PATH] --compatible
-    ours-install server access-issue --state-dir PATH --output PATH
-    ours-install server access-replace --state-dir PATH --confirm
-    ours-install server backup|restore server LABEL --state-dir PATH
-    ours-install server backup|restore daemon|telegram|cowork|messenger LABEL --state-dir PATH
-    ours-install server reset daemon|telegram|cowork|messenger --confirm --state-dir PATH
-    ours-install client install --config PATH
-  Client profile settings select installer.integrations and may override installer.sourcesPath,
-  and optional installer.fleetSettingsPath (relative paths use the profile directory).
-  Repeat selected server install repairs setup without replacing existing authority.
-  Daemon maintenance includes MCP state. Full-server reset is not supported.
-  Update requires reviewed storage compatibility; --compatible records that attestation.
-  Existing managed layouts are converted before service startup.
+  Full stack, with every required answer preset (no prompts):
+    ours-install --mode docker --state-dir /private/ours --identity-name "Your Name" --integrations codex,fleet --fleet-settings /private/fleet.json
 
+  Server preset (native is an alias for packages):
+    ours-install server --mode native --state-dir /private/ours --identity-name "Your Name"
+    ours-install server install --mode docker --state-dir /private/ours --identity-name "Your Name"
 
-  Install:  npm i -g @ours.network/install && ours-install   (recommended)
-            npx @ours.network/install                          (one-off)
+  Client preset for an existing server:
+    ours-install client --config /private/profile.json --integrations codex,fleet --fleet-settings /private/fleet.json
 
-  ours-install [--state-dir PATH] [--port N] [--dry-run] [--help] [--version]
+  Update a retained installation, preserving its identities:
+    ours-install all update --mode docker --state-dir /private/ours --identity-name "Your Name" --integrations codex,fleet --fleet-settings /private/fleet.json --compatible
 
-Progress-driven setup for the whole stack: one shared daemon, MCP, Telegram,
-cowork, detected harness plugins (Claude Code / Codex / Hermes), a Human
-identity, and ours-fleet. The daemon, Telegram connector, and cowork shim start
-as durable services; only Fleet is staged but stopped. The installer asks only
-for information it cannot infer and
-ends with exact next commands plus a copy-paste agent hand-off prompt.
+  --scope all|server|client   preset which parts to configure (default all)
+  --action install|update    equivalent to the positional operation
+  --mode docker|native      packages is also accepted for native mode
+  --state-dir PATH          installation root; required for all/server
+  --identity-name NAME      desired Human name for a fresh server; existing root is retained
+  --integrations LIST       codex,claude-code,fleet; use none to skip clients explicitly
+  --fleet-settings PATH     JSON settings for Fleet; mandatory for CLI presets selecting Fleet
+  --config PATH             complete connection profile for client-only setup
+  --sources PATH            explicit full development source policy override
+  --port N                  daemon port (default 3050 on a fresh installation)
+  --cowork-port N           cowork port (default 3052)
+  --messenger-port N        messenger port (default 8420)
+  --compatible              required attestation for server updates of retained state
+  --migrate                 explicit legacy access migration during install
+  --dry-run                 show the validated plan without changing anything
+  --help, -h                show help
+  --version, -V             print installer version
 
-  --state-dir  the daemon's STATE DIRECTORY, which is what identifies a daemon
-               (default ~/.ours). A second state directory is a second daemon.
-  --port       used only when CREATING a daemon. For a daemon that already owns
-               the state directory the port comes from its own record, and a
-               --port that disagrees with it is refused rather than corrected.
-  --dry-run    walk the whole flow and print what it WOULD do — change nothing
-  --help       show this help and exit
-  --version    print the installer version and exit
+CLI presets must be complete and never open the interactive form or a Fleet wizard.
+Missing answers are reported before installation. Both input modes run the same
+installer with preparation, identity restoration, update and readiness progress.
+Fleet is configured but left stopped for operator review.
+
+Scoped maintenance:
+  ours-install server status|start|stop|restart|rebuild --state-dir PATH
+  ours-install server access-issue --state-dir PATH --output PATH
+  ours-install server access-replace --state-dir PATH --confirm
+  ours-install server backup|restore server|daemon|telegram|cowork|messenger LABEL --state-dir PATH
+  ours-install server reset daemon|telegram|cowork|messenger --state-dir PATH --confirm
 
-Env: OURS_ASSUME_YES=1 (accept defaults, no prompts) · OURS_INSTALL_DRY_RUN=1 ·
-     OURS_CONFIG=/private/host-profile.json · OURS_CHANNEL=nightly ·
-     OURS_BROKER_URL · OURS_NPM. A complete host profile selects client-only
-     setup for an existing Compose-owned daemon. Docs: https://ours.network`;
+Install the selected channel with npm install -g @ours.network/install@nightly
+(or @latest for a qualified stable release). Component versions come from the
+installer's embedded release manifest. Node.js 22+ is required.
+`;
 
 export const UNINSTALL_USAGE = `ours-uninstall — remove one ours daemon and what attaches to it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/install",
-  "version": "1.2.0-nightly.2",
+  "version": "1.2.1-nightly.2",
   "private": false,
   "description": "The all-in-one ours.network installer: one shared daemon, MCP, cowork, Telegram, Fleet initialization, harness plugins, Human identity, progress UI, and guided next steps.",
   "type": "module",
@@ -19,17 +19,18 @@
   ],
   "license": "FSL-1.1-Apache-2.0",
   "author": "Adapt Toolkit",
-  "homepage": "https://github.com/adapt-toolkit/ours-mcp/tree/main/packages/installer#readme",
+  "homepage": "https://github.com/adapt-toolkit/ours-network/tree/main/packages/installer#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/adapt-toolkit/ours-mcp.git",
+    "url": "git+https://github.com/adapt-toolkit/ours-network.git",
     "directory": "packages/installer"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepack": "node ../../scripts/prepare-installer.mjs"
   },
   "dependencies": {
     "koffi": "3.2.1",